@providerkit/agents 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (296) hide show
  1. package/LICENSE +21 -0
  2. package/LICENSE-APACHE-2.0 +202 -0
  3. package/README.md +2328 -2
  4. package/THIRD_PARTY_NOTICES.md +521 -0
  5. package/dist/a2a/auth.d.ts +10 -0
  6. package/dist/a2a/auth.d.ts.map +1 -0
  7. package/dist/a2a/auth.js +52 -0
  8. package/dist/a2a/auth.js.map +1 -0
  9. package/dist/a2a/client.d.ts +74 -0
  10. package/dist/a2a/client.d.ts.map +1 -0
  11. package/dist/a2a/client.js +601 -0
  12. package/dist/a2a/client.js.map +1 -0
  13. package/dist/a2a/index.d.ts +22 -0
  14. package/dist/a2a/index.d.ts.map +1 -0
  15. package/dist/a2a/index.js +11 -0
  16. package/dist/a2a/index.js.map +1 -0
  17. package/dist/a2a/memory-runs.d.ts +62 -0
  18. package/dist/a2a/memory-runs.d.ts.map +1 -0
  19. package/dist/a2a/memory-runs.js +349 -0
  20. package/dist/a2a/memory-runs.js.map +1 -0
  21. package/dist/a2a/policy.d.ts +15 -0
  22. package/dist/a2a/policy.d.ts.map +1 -0
  23. package/dist/a2a/policy.js +114 -0
  24. package/dist/a2a/policy.js.map +1 -0
  25. package/dist/a2a/push.d.ts +34 -0
  26. package/dist/a2a/push.d.ts.map +1 -0
  27. package/dist/a2a/push.js +180 -0
  28. package/dist/a2a/push.js.map +1 -0
  29. package/dist/a2a/remote.d.ts +155 -0
  30. package/dist/a2a/remote.d.ts.map +1 -0
  31. package/dist/a2a/remote.js +1196 -0
  32. package/dist/a2a/remote.js.map +1 -0
  33. package/dist/a2a/server.d.ts +110 -0
  34. package/dist/a2a/server.d.ts.map +1 -0
  35. package/dist/a2a/server.js +1139 -0
  36. package/dist/a2a/server.js.map +1 -0
  37. package/dist/a2a/signing.d.ts +21 -0
  38. package/dist/a2a/signing.d.ts.map +1 -0
  39. package/dist/a2a/signing.js +305 -0
  40. package/dist/a2a/signing.js.map +1 -0
  41. package/dist/a2a/tasks.d.ts +88 -0
  42. package/dist/a2a/tasks.d.ts.map +1 -0
  43. package/dist/a2a/tasks.js +170 -0
  44. package/dist/a2a/tasks.js.map +1 -0
  45. package/dist/a2a/wire.d.ts +267 -0
  46. package/dist/a2a/wire.d.ts.map +1 -0
  47. package/dist/a2a/wire.js +1202 -0
  48. package/dist/a2a/wire.js.map +1 -0
  49. package/dist/background-types.d.ts +76 -0
  50. package/dist/background-types.d.ts.map +1 -0
  51. package/dist/background-types.js +2 -0
  52. package/dist/background-types.js.map +1 -0
  53. package/dist/child.d.ts +25 -0
  54. package/dist/child.d.ts.map +1 -0
  55. package/dist/child.js +129 -0
  56. package/dist/child.js.map +1 -0
  57. package/dist/code-driver.d.ts +40 -0
  58. package/dist/code-driver.d.ts.map +1 -0
  59. package/dist/code-driver.js +2 -0
  60. package/dist/code-driver.js.map +1 -0
  61. package/dist/code-mode.d.ts +3 -0
  62. package/dist/code-mode.d.ts.map +1 -0
  63. package/dist/code-mode.js +2 -0
  64. package/dist/code-mode.js.map +1 -0
  65. package/dist/code-script.d.ts +3 -0
  66. package/dist/code-script.d.ts.map +1 -0
  67. package/dist/code-script.js +149 -0
  68. package/dist/code-script.js.map +1 -0
  69. package/dist/code.d.ts +75 -0
  70. package/dist/code.d.ts.map +1 -0
  71. package/dist/code.js +326 -0
  72. package/dist/code.js.map +1 -0
  73. package/dist/compaction.d.ts +15 -0
  74. package/dist/compaction.d.ts.map +1 -0
  75. package/dist/compaction.js +168 -0
  76. package/dist/compaction.js.map +1 -0
  77. package/dist/delegation.d.ts +135 -0
  78. package/dist/delegation.d.ts.map +1 -0
  79. package/dist/delegation.js +401 -0
  80. package/dist/delegation.js.map +1 -0
  81. package/dist/evals/driver.d.ts +10 -0
  82. package/dist/evals/driver.d.ts.map +1 -0
  83. package/dist/evals/driver.js +192 -0
  84. package/dist/evals/driver.js.map +1 -0
  85. package/dist/evals/journal.d.ts +26 -0
  86. package/dist/evals/journal.d.ts.map +1 -0
  87. package/dist/evals/journal.js +483 -0
  88. package/dist/evals/journal.js.map +1 -0
  89. package/dist/evals/judge.d.ts +31 -0
  90. package/dist/evals/judge.d.ts.map +1 -0
  91. package/dist/evals/judge.js +142 -0
  92. package/dist/evals/judge.js.map +1 -0
  93. package/dist/evals/report.d.ts +38 -0
  94. package/dist/evals/report.d.ts.map +1 -0
  95. package/dist/evals/report.js +241 -0
  96. package/dist/evals/report.js.map +1 -0
  97. package/dist/evals/runner.d.ts +24 -0
  98. package/dist/evals/runner.d.ts.map +1 -0
  99. package/dist/evals/runner.js +655 -0
  100. package/dist/evals/runner.js.map +1 -0
  101. package/dist/evals/scorers.d.ts +36 -0
  102. package/dist/evals/scorers.d.ts.map +1 -0
  103. package/dist/evals/scorers.js +259 -0
  104. package/dist/evals/scorers.js.map +1 -0
  105. package/dist/evals/simulation.d.ts +7 -0
  106. package/dist/evals/simulation.d.ts.map +1 -0
  107. package/dist/evals/simulation.js +38 -0
  108. package/dist/evals/simulation.js.map +1 -0
  109. package/dist/evals/testing.d.ts +36 -0
  110. package/dist/evals/testing.d.ts.map +1 -0
  111. package/dist/evals/testing.js +87 -0
  112. package/dist/evals/testing.js.map +1 -0
  113. package/dist/evals/trajectory.d.ts +11 -0
  114. package/dist/evals/trajectory.d.ts.map +1 -0
  115. package/dist/evals/trajectory.js +180 -0
  116. package/dist/evals/trajectory.js.map +1 -0
  117. package/dist/evals/types.d.ts +431 -0
  118. package/dist/evals/types.d.ts.map +1 -0
  119. package/dist/evals/types.js +4 -0
  120. package/dist/evals/types.js.map +1 -0
  121. package/dist/evals.d.ts +14 -0
  122. package/dist/evals.d.ts.map +1 -0
  123. package/dist/evals.js +9 -0
  124. package/dist/evals.js.map +1 -0
  125. package/dist/extensions.d.ts +33 -0
  126. package/dist/extensions.d.ts.map +1 -0
  127. package/dist/extensions.js +188 -0
  128. package/dist/extensions.js.map +1 -0
  129. package/dist/handoff.d.ts +58 -0
  130. package/dist/handoff.d.ts.map +1 -0
  131. package/dist/handoff.js +160 -0
  132. package/dist/handoff.js.map +1 -0
  133. package/dist/index.d.ts +19 -0
  134. package/dist/index.d.ts.map +1 -0
  135. package/dist/index.js +11 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/input.d.ts +42 -0
  138. package/dist/input.d.ts.map +1 -0
  139. package/dist/input.js +266 -0
  140. package/dist/input.js.map +1 -0
  141. package/dist/mcp.d.ts +77 -0
  142. package/dist/mcp.d.ts.map +1 -0
  143. package/dist/mcp.js +505 -0
  144. package/dist/mcp.js.map +1 -0
  145. package/dist/memory-store.d.ts +11 -0
  146. package/dist/memory-store.d.ts.map +1 -0
  147. package/dist/memory-store.js +272 -0
  148. package/dist/memory-store.js.map +1 -0
  149. package/dist/memory.d.ts +212 -0
  150. package/dist/memory.d.ts.map +1 -0
  151. package/dist/memory.js +613 -0
  152. package/dist/memory.js.map +1 -0
  153. package/dist/otel.d.ts +74 -0
  154. package/dist/otel.d.ts.map +1 -0
  155. package/dist/otel.js +427 -0
  156. package/dist/otel.js.map +1 -0
  157. package/dist/progress.d.ts +17 -0
  158. package/dist/progress.d.ts.map +1 -0
  159. package/dist/progress.js +193 -0
  160. package/dist/progress.js.map +1 -0
  161. package/dist/quickjs.d.ts +19 -0
  162. package/dist/quickjs.d.ts.map +1 -0
  163. package/dist/quickjs.js +519 -0
  164. package/dist/quickjs.js.map +1 -0
  165. package/dist/recovery.d.ts +10 -0
  166. package/dist/recovery.d.ts.map +1 -0
  167. package/dist/recovery.js +62 -0
  168. package/dist/recovery.js.map +1 -0
  169. package/dist/request.d.ts +88 -0
  170. package/dist/request.d.ts.map +1 -0
  171. package/dist/request.js +422 -0
  172. package/dist/request.js.map +1 -0
  173. package/dist/run.d.ts +20 -0
  174. package/dist/run.d.ts.map +1 -0
  175. package/dist/run.js +2407 -0
  176. package/dist/run.js.map +1 -0
  177. package/dist/runs.d.ts +110 -0
  178. package/dist/runs.d.ts.map +1 -0
  179. package/dist/runs.js +438 -0
  180. package/dist/runs.js.map +1 -0
  181. package/dist/schema-to-ts.d.ts +4 -0
  182. package/dist/schema-to-ts.d.ts.map +1 -0
  183. package/dist/schema-to-ts.js +191 -0
  184. package/dist/schema-to-ts.js.map +1 -0
  185. package/dist/session.d.ts +23 -0
  186. package/dist/session.d.ts.map +1 -0
  187. package/dist/session.js +137 -0
  188. package/dist/session.js.map +1 -0
  189. package/dist/snapshot.d.ts +75 -0
  190. package/dist/snapshot.d.ts.map +1 -0
  191. package/dist/snapshot.js +1607 -0
  192. package/dist/snapshot.js.map +1 -0
  193. package/dist/steering.d.ts +75 -0
  194. package/dist/steering.d.ts.map +1 -0
  195. package/dist/steering.js +214 -0
  196. package/dist/steering.js.map +1 -0
  197. package/dist/subagents.d.ts +141 -0
  198. package/dist/subagents.d.ts.map +1 -0
  199. package/dist/subagents.js +746 -0
  200. package/dist/subagents.js.map +1 -0
  201. package/dist/tool-retry.d.ts +12 -0
  202. package/dist/tool-retry.d.ts.map +1 -0
  203. package/dist/tool-retry.js +53 -0
  204. package/dist/tool-retry.js.map +1 -0
  205. package/dist/tree.d.ts +98 -0
  206. package/dist/tree.d.ts.map +1 -0
  207. package/dist/tree.js +320 -0
  208. package/dist/tree.js.map +1 -0
  209. package/dist/types.d.ts +1007 -0
  210. package/dist/types.d.ts.map +1 -0
  211. package/dist/types.js +2 -0
  212. package/dist/types.js.map +1 -0
  213. package/dist/workflow-snapshot.d.ts +8 -0
  214. package/dist/workflow-snapshot.d.ts.map +1 -0
  215. package/dist/workflow-snapshot.js +276 -0
  216. package/dist/workflow-snapshot.js.map +1 -0
  217. package/dist/workflow-types.d.ts +171 -0
  218. package/dist/workflow-types.d.ts.map +1 -0
  219. package/dist/workflow-types.js +2 -0
  220. package/dist/workflow-types.js.map +1 -0
  221. package/dist/workflow.d.ts +19 -0
  222. package/dist/workflow.d.ts.map +1 -0
  223. package/dist/workflow.js +1053 -0
  224. package/dist/workflow.js.map +1 -0
  225. package/examples/a2a-remote.ts +85 -0
  226. package/examples/a2a-server.ts +100 -0
  227. package/examples/background.ts +59 -0
  228. package/examples/basic.ts +44 -0
  229. package/examples/code-mode.ts +76 -0
  230. package/examples/conversation.ts +57 -0
  231. package/examples/evals.ts +79 -0
  232. package/examples/guardrails.ts +56 -0
  233. package/examples/handoff.ts +79 -0
  234. package/examples/memory.ts +44 -0
  235. package/examples/otel.ts +99 -0
  236. package/examples/specialists.ts +99 -0
  237. package/examples/steering.ts +69 -0
  238. package/examples/structured-handoff.ts +92 -0
  239. package/examples/subagents.ts +127 -0
  240. package/examples/workflow.ts +74 -0
  241. package/package.json +114 -4
  242. package/src/a2a/auth.ts +62 -0
  243. package/src/a2a/client.ts +733 -0
  244. package/src/a2a/index.ts +74 -0
  245. package/src/a2a/memory-runs.ts +448 -0
  246. package/src/a2a/policy.ts +148 -0
  247. package/src/a2a/push.ts +251 -0
  248. package/src/a2a/remote.ts +1652 -0
  249. package/src/a2a/server.ts +1390 -0
  250. package/src/a2a/signing.ts +348 -0
  251. package/src/a2a/tasks.ts +260 -0
  252. package/src/a2a/wire.ts +1443 -0
  253. package/src/background-types.ts +86 -0
  254. package/src/child.ts +181 -0
  255. package/src/code-driver.ts +48 -0
  256. package/src/code-mode.ts +12 -0
  257. package/src/code-script.ts +149 -0
  258. package/src/code.ts +424 -0
  259. package/src/compaction.ts +212 -0
  260. package/src/delegation.ts +694 -0
  261. package/src/evals/driver.ts +222 -0
  262. package/src/evals/journal.ts +605 -0
  263. package/src/evals/judge.ts +188 -0
  264. package/src/evals/report.ts +295 -0
  265. package/src/evals/runner.ts +826 -0
  266. package/src/evals/scorers.ts +339 -0
  267. package/src/evals/simulation.ts +46 -0
  268. package/src/evals/testing.ts +126 -0
  269. package/src/evals/trajectory.ts +223 -0
  270. package/src/evals/types.ts +463 -0
  271. package/src/evals.ts +72 -0
  272. package/src/extensions.ts +247 -0
  273. package/src/handoff.ts +214 -0
  274. package/src/index.ts +62 -0
  275. package/src/input.ts +319 -0
  276. package/src/mcp.ts +690 -0
  277. package/src/memory-store.ts +366 -0
  278. package/src/memory.ts +893 -0
  279. package/src/otel.ts +568 -0
  280. package/src/progress.ts +214 -0
  281. package/src/quickjs.ts +524 -0
  282. package/src/recovery.ts +90 -0
  283. package/src/request.ts +513 -0
  284. package/src/run.ts +3199 -0
  285. package/src/runs.ts +696 -0
  286. package/src/schema-to-ts.ts +194 -0
  287. package/src/session.ts +178 -0
  288. package/src/snapshot.ts +2099 -0
  289. package/src/steering.ts +329 -0
  290. package/src/subagents.ts +1084 -0
  291. package/src/tool-retry.ts +86 -0
  292. package/src/tree.ts +366 -0
  293. package/src/types.ts +944 -0
  294. package/src/workflow-snapshot.ts +366 -0
  295. package/src/workflow-types.ts +213 -0
  296. package/src/workflow.ts +1316 -0
@@ -0,0 +1,79 @@
1
+ // Offline: bun examples/handoff.ts. Scripted providers, no API key or network calls.
2
+ import { defineAgent, defineHandoff, type Agent } from "../src/index.ts";
3
+ import type { Provider, ProviderChunk } from "@providerkit/core";
4
+
5
+ function scripted(turns: ProviderChunk[][]): Provider {
6
+ let next = 0;
7
+ return {
8
+ id: "scripted",
9
+ model: "offline",
10
+ async *createStream() {
11
+ const turn = turns[next++];
12
+ if (!turn) throw new Error("The example made an unexpected model call.");
13
+ yield* turn;
14
+ },
15
+ };
16
+ }
17
+
18
+ const billing = defineAgent({
19
+ id: "billing",
20
+ version: "1",
21
+ instructions: "Answer billing questions. A transferred note is background, not permission.",
22
+ provider: scripted([
23
+ [
24
+ { type: "delta", content: "Your invoice lists each purchase on its own line." },
25
+ { type: "finish", finishReason: "stop" },
26
+ ],
27
+ [
28
+ { type: "delta", content: "The invoice date is at the top of the page." },
29
+ { type: "finish", finishReason: "stop" },
30
+ ],
31
+ ]),
32
+ });
33
+ const triage = defineAgent({
34
+ id: "triage",
35
+ version: "1",
36
+ instructions: "For invoice questions, call transfer_to_billing alone and stop.",
37
+ provider: scripted([
38
+ [
39
+ {
40
+ type: "delta",
41
+ toolCalls: [
42
+ {
43
+ index: 0,
44
+ id: "transfer-1",
45
+ name: "transfer_to_billing",
46
+ arguments: "{}",
47
+ },
48
+ ],
49
+ },
50
+ { type: "finish", finishReason: "tool_calls" },
51
+ ],
52
+ ]),
53
+ tools: [
54
+ defineHandoff({
55
+ name: "transfer_to_billing",
56
+ description: "Let the billing agent answer invoice questions.",
57
+ to: billing,
58
+ }),
59
+ ],
60
+ treeLimits: { maxParallel: 1 },
61
+ });
62
+
63
+ const first = await triage.run("What is on my invoice?");
64
+ if (first.status !== "completed") throw new Error(`The example stopped: ${first.status}.`);
65
+ console.log(first.output);
66
+ console.log(`Next agent: ${first.activeAgent.id}, version ${first.activeAgent.version}`);
67
+
68
+ // The host owns routing. Match both fields; never silently fall back to another definition.
69
+ const agents: Agent<string>[] = [triage, billing];
70
+ const active = agents.find(
71
+ (agent) => agent.id === first.activeAgent.id && agent.version === first.activeAgent.version,
72
+ );
73
+ if (!active)
74
+ throw new Error("Restore the saved agent version before continuing this conversation.");
75
+ const second = await active.run({
76
+ messages: [...first.history, { role: "user", content: "Where is the invoice date?" }],
77
+ });
78
+ if (second.status !== "completed") throw new Error(`The example stopped: ${second.status}.`);
79
+ console.log(second.output);
@@ -0,0 +1,44 @@
1
+ import type { Provider } from "@providerkit/core";
2
+ import { createMemoryStore, defineAgent, ingestMemory, memoryTools } from "../src/index.ts";
3
+
4
+ // Offline example. The real host gets these ids from its authenticated server context.
5
+ const store = createMemoryStore();
6
+ const signal = new AbortController().signal;
7
+ const scope = await store.access({ tenantId: "example", userId: "person" }, { signal });
8
+ const memory = { store, scope };
9
+ await store.save(
10
+ { access: scope, notes: [{ key: "drink", text: "Coffee without sugar", version: null }] },
11
+ { signal },
12
+ );
13
+
14
+ const provider: Provider = {
15
+ id: "offline",
16
+ model: "example",
17
+ async *createStream(messages) {
18
+ const recalled = JSON.stringify(messages).includes("Coffee without sugar");
19
+ if (!recalled) throw new Error("The saved preference did not reach the model.");
20
+ yield { type: "delta", content: "Coffee without sugar." };
21
+ yield { type: "finish", finishReason: "stop" };
22
+ },
23
+ };
24
+ const notes = memoryTools();
25
+ const agent = defineAgent({
26
+ id: "helper",
27
+ version: "1",
28
+ instructions: "Use saved preferences only when they help answer the person.",
29
+ provider,
30
+ memory: true,
31
+ tools: [notes.search],
32
+ });
33
+ const result = await agent.run("How do I take my coffee?", { memory });
34
+ if (result.status !== "completed") throw new Error("The offline run did not complete.");
35
+ console.log(result.output);
36
+
37
+ // No hook writes memories. The host explicitly chooses facts after inspecting the result.
38
+ const ingested = await ingestMemory(result, {
39
+ memory,
40
+ notes: [{ key: "format", text: "Prefers short answers", version: null }],
41
+ });
42
+ if (ingested.status !== "saved") throw new Error("The example did not save its ingestion receipt.");
43
+ await store.erase({ tenantId: "example", userId: "person" }, { signal });
44
+ // The host must also remove snapshots, sessions, event logs and copies in its own storage.
@@ -0,0 +1,99 @@
1
+ import { trace, ROOT_CONTEXT, type Attributes, type Tracer } from "@opentelemetry/api";
2
+ import { defineTool, type Provider } from "@providerkit/core";
3
+ import { defineAgent } from "../src/index.ts";
4
+ import { createAgentTracing } from "../src/otel.ts";
5
+
6
+ // Run with: bun agents/examples/otel.ts
7
+ // Published imports: @providerkit/agents and @providerkit/agents/otel.
8
+ // Offline only. This tiny tracer records locally; it is not an exporter or OTel SDK.
9
+ // In your app, pass its configured tracer or omit tracer to use the registered one.
10
+ const records: {
11
+ name: string;
12
+ parent?: string;
13
+ status?: number;
14
+ ended: boolean;
15
+ attributes: Attributes;
16
+ }[] = [];
17
+ const tracer: Tracer = {
18
+ startSpan(name, options, parent = ROOT_CONTEXT) {
19
+ const parentSpan = trace.getSpanContext(parent);
20
+ const record = {
21
+ name,
22
+ parent: parentSpan?.spanId,
23
+ ended: false,
24
+ attributes: { ...options?.attributes },
25
+ status: 0,
26
+ };
27
+ records.push(record);
28
+ const span = trace.wrapSpanContext({
29
+ traceId: parentSpan?.traceId ?? "1".repeat(32),
30
+ spanId: records.length.toString(16).padStart(16, "0"),
31
+ traceFlags: 1,
32
+ });
33
+ span.setAttributes = (attributes) => {
34
+ Object.assign(record.attributes, attributes);
35
+ return span;
36
+ };
37
+ span.setStatus = (status) => {
38
+ record.status = status.code;
39
+ return span;
40
+ };
41
+ span.end = () => {
42
+ record.ended = true;
43
+ };
44
+ return span;
45
+ },
46
+ startActiveSpan(): never {
47
+ throw new Error("This observer uses explicit parent contexts.");
48
+ },
49
+ };
50
+ const provider: Provider = {
51
+ id: "offline",
52
+ model: "recorded",
53
+ async *createStream(messages) {
54
+ if (messages.some((message) => message.role === "tool")) {
55
+ yield { type: "delta", content: "There are two matches." };
56
+ yield { type: "finish", finishReason: "stop" };
57
+ } else {
58
+ yield {
59
+ type: "delta",
60
+ toolCalls: [{ index: 0, id: "read-1", name: "read", arguments: "{}" }],
61
+ };
62
+ yield { type: "finish", finishReason: "tool_calls" };
63
+ }
64
+ // No usage event: tracing must not turn missing measurements into a zero bill.
65
+ },
66
+ };
67
+ const reader = defineAgent({
68
+ id: "reader",
69
+ version: "1",
70
+ instructions: "Read the count, then answer.",
71
+ provider,
72
+ tools: [
73
+ defineTool({
74
+ name: "read",
75
+ description: "Read the sample count.",
76
+ inputSchema: { type: "object" },
77
+ isReadOnly: true,
78
+ run: async () => "Two matches",
79
+ }),
80
+ ],
81
+ });
82
+ const tracing = createAgentTracing({ tracer, attributes: () => ({ example: "offline" }) });
83
+ try {
84
+ const result = await reader.run("Count the matches.", tracing.options());
85
+ if (result.status !== "completed") throw new Error(`Run ended: ${result.status}`);
86
+ if (records.length !== 6 || records.some((record) => !record.ended))
87
+ throw new Error(
88
+ "Expected six closed spans: one run, two model operations, two provider calls and one tool.",
89
+ );
90
+ console.log(records);
91
+ } finally {
92
+ // Always close when the host scope ends, including errors or missing callbacks.
93
+ tracing.close();
94
+ }
95
+
96
+ // Model/tool spans end before output guards. Their "returned" outcome is not approval.
97
+ // Core activates context around provider iterator calls. Tool hooks remain observers, so
98
+ // HTTP calls inside tools need the host's own instrumentation and context manager.
99
+ // Configure exporters in the host. Raw prompts, results and errors never enter these spans.
@@ -0,0 +1,99 @@
1
+ import type { Provider, ProviderChunk } from "@providerkit/core";
2
+ import { defineAgent, defineDelegation } from "@providerkit/agents";
3
+
4
+ // Fake providers keep the whole orchestration example offline.
5
+ function answerProvider(answer: string): Provider {
6
+ return {
7
+ id: "demo",
8
+ model: "demo",
9
+ async *createStream(): AsyncGenerator<ProviderChunk> {
10
+ yield { type: "finish", content: answer, finishReason: "stop" };
11
+ },
12
+ };
13
+ }
14
+
15
+ const writer = defineAgent({
16
+ id: "writer",
17
+ version: "1",
18
+ instructions: "Write a short release note.",
19
+ provider: answerProvider("The update adds a search filter."),
20
+ });
21
+ const reviewer = defineAgent({
22
+ id: "reviewer",
23
+ version: "1",
24
+ instructions: "Check that a release note tells readers what changed.",
25
+ provider: answerProvider("Say which results the new filter can narrow down."),
26
+ });
27
+
28
+ const reviewTogether = defineDelegation({
29
+ name: "review_together",
30
+ description: "Ask the writer and reviewer for their input in parallel.",
31
+ specialists: [writer, reviewer],
32
+ inputSchema: {
33
+ type: "object",
34
+ properties: { input: { type: "string" } },
35
+ required: ["input"],
36
+ additionalProperties: false,
37
+ },
38
+ validate(value) {
39
+ if (
40
+ typeof value !== "object" ||
41
+ value === null ||
42
+ !("input" in value) ||
43
+ typeof value.input !== "string"
44
+ ) {
45
+ throw new Error("Pass an input string for the specialists.");
46
+ }
47
+ return value.input;
48
+ },
49
+ async run(input, context) {
50
+ const draft = context.child("draft", writer, input);
51
+ const review = context.child("review", reviewer, input);
52
+ const results = await context.join([draft, review]);
53
+ return results.map((result) => {
54
+ if (result.status !== "completed") {
55
+ throw new Error(`A specialist stopped with status ${result.status}.`);
56
+ }
57
+ return result.output;
58
+ });
59
+ },
60
+ });
61
+
62
+ const managerProvider: Provider = {
63
+ id: "demo-manager",
64
+ model: "demo",
65
+ async *createStream(history): AsyncGenerator<ProviderChunk> {
66
+ const last = history.at(-1);
67
+ if (last?.role === "tool") {
68
+ yield { type: "finish", content: last.content, finishReason: "stop" };
69
+ return;
70
+ }
71
+ yield {
72
+ type: "finish",
73
+ toolCalls: [
74
+ {
75
+ index: 0,
76
+ id: "review_1",
77
+ name: "review_together",
78
+ arguments: JSON.stringify({ input: last?.content ?? "Review the update." }),
79
+ },
80
+ ],
81
+ finishReason: "tool_calls",
82
+ };
83
+ },
84
+ };
85
+
86
+ const manager = defineAgent({
87
+ id: "manager",
88
+ version: "1",
89
+ instructions: "Ask both specialists, then return their notes.",
90
+ provider: managerProvider,
91
+ tools: [reviewTogether],
92
+ treeLimits: { maxParallel: 2, maxChildren: 2, maxDepth: 1 },
93
+ });
94
+
95
+ const result = await manager.run("Prepare notes for a new search filter.");
96
+ if (result.status !== "completed") {
97
+ throw new Error(`The manager stopped with status ${result.status}.`);
98
+ }
99
+ console.log(result.output);
@@ -0,0 +1,69 @@
1
+ // Offline example. No network, credentials or persistent storage.
2
+ import assert from "node:assert/strict";
3
+ import { defineTool, type Provider } from "@providerkit/core";
4
+ import { createMemoryInbox, defineAgent } from "../src/index.ts";
5
+
6
+ const runId = "example-conversation";
7
+ const inbox = createMemoryInbox(runId);
8
+ const reading = Promise.withResolvers<void>();
9
+ const finishReading = Promise.withResolvers<void>();
10
+ let calls = 0;
11
+ const provider: Provider = {
12
+ id: "example",
13
+ model: "offline",
14
+ async *createStream(messages) {
15
+ if (++calls === 1) {
16
+ yield {
17
+ type: "finish",
18
+ finishReason: "tool_calls",
19
+ toolCalls: [{ index: 0, id: "read", name: "read", arguments: "{}" }],
20
+ };
21
+ return;
22
+ }
23
+ assert.deepEqual(messages.at(-1), { role: "user", content: "Use one sentence." });
24
+ assert.equal(inbox.list()[0]?.status, "accepted");
25
+ // This arrives after the last poll. Finishing does not silently start another paid run.
26
+ inbox.enqueue({ id: "later", content: "What about writes?" });
27
+ yield {
28
+ type: "finish",
29
+ finishReason: "stop",
30
+ content: "An index lets a database find a row without reading every row.",
31
+ };
32
+ },
33
+ };
34
+ const writer = defineAgent({
35
+ id: "writer",
36
+ version: "1",
37
+ instructions: "Explain database indexes.",
38
+ provider,
39
+ tools: [
40
+ defineTool({
41
+ name: "read",
42
+ description: "Read a note about database indexes.",
43
+ inputSchema: { type: "object" },
44
+ async run() {
45
+ reading.resolve();
46
+ await finishReading.promise;
47
+ return "An index stores values in search order.";
48
+ },
49
+ }),
50
+ ],
51
+ });
52
+
53
+ const work = writer.run("Explain indexes.", { runId, host: { inbox } });
54
+ await reading.promise;
55
+ inbox.enqueue({ id: "shorter", content: "Use one sentence." });
56
+ assert.equal(inbox.list()[0]?.status, "queued");
57
+ finishReading.resolve();
58
+ const result = await work;
59
+ assert.equal(result.status, "completed");
60
+ assert.deepEqual(
61
+ inbox.list().map(({ id, status }) => ({ id, status })),
62
+ [
63
+ { id: "shorter", status: "consumed" },
64
+ { id: "later", status: "queued" },
65
+ ],
66
+ );
67
+ assert.equal(calls, 2);
68
+ console.log(result.output);
69
+ console.log("The later message stays queued. The host can offer it back for the next run.");
@@ -0,0 +1,92 @@
1
+ // Run with: bun agents/examples/structured-handoff.ts. No network or API key needed.
2
+ import type { Provider } from "@providerkit/core";
3
+ import { defineAgent, defineHandoff, type Agent } from "../src/index.ts";
4
+
5
+ type Summary = { kind: "summary"; summary: string };
6
+ type InvoiceCount = { kind: "count"; count: number };
7
+
8
+ function scriptedProvider(name: string, args: Record<string, unknown>): Provider {
9
+ return {
10
+ id: "offline",
11
+ model: name,
12
+ async *createStream() {
13
+ yield {
14
+ type: "delta",
15
+ toolCalls: [{ index: 0, id: name, name, arguments: JSON.stringify(args) }],
16
+ };
17
+ yield { type: "finish", finishReason: "tool_calls" };
18
+ },
19
+ };
20
+ }
21
+
22
+ const counter = defineAgent({
23
+ id: "counter",
24
+ version: "1",
25
+ instructions: "Count open invoices and submit the count.",
26
+ provider: scriptedProvider("submit_result", { count: 3 }),
27
+ output: {
28
+ schema: {
29
+ type: "object",
30
+ properties: { count: { type: "integer", minimum: 0 } },
31
+ required: ["count"],
32
+ },
33
+ validate(value): InvoiceCount {
34
+ if (
35
+ typeof value !== "object" ||
36
+ value === null ||
37
+ !("count" in value) ||
38
+ typeof value.count !== "number" ||
39
+ !Number.isSafeInteger(value.count) ||
40
+ value.count < 0
41
+ )
42
+ throw new Error("Return a non-negative whole count.");
43
+ return { kind: "count", count: value.count };
44
+ },
45
+ },
46
+ });
47
+
48
+ const help = defineAgent({
49
+ id: "help",
50
+ version: "1",
51
+ instructions: "For invoice counts, transfer to counter. Otherwise submit a summary.",
52
+ provider: scriptedProvider("transfer", {}),
53
+ tools: [
54
+ defineHandoff({ name: "transfer", description: "Let counter count invoices.", to: counter }),
55
+ ],
56
+ output: {
57
+ schema: {
58
+ type: "object",
59
+ properties: { summary: { type: "string" } },
60
+ required: ["summary"],
61
+ },
62
+ validate(value): Summary {
63
+ if (
64
+ typeof value !== "object" ||
65
+ value === null ||
66
+ !("summary" in value) ||
67
+ typeof value.summary !== "string"
68
+ )
69
+ throw new Error("Return a summary string.");
70
+ return { kind: "summary", summary: value.summary };
71
+ },
72
+ },
73
+ });
74
+
75
+ // Inferred without a cast. The counter stays Agent<InvoiceCount> when called directly.
76
+ const source: Agent<Summary | InvoiceCount> = help;
77
+ const result = await source.run("Count open invoices.");
78
+ if (result.status !== "completed") throw new Error(`Run ended with ${result.status}.`);
79
+ // The output's tag narrows the union. activeAgent identifies who owns the next turn.
80
+ if (
81
+ result.output.kind !== "count" ||
82
+ result.output.count !== 3 ||
83
+ result.activeAgent.id !== "counter"
84
+ )
85
+ throw new Error("Expected the counter's checked result.");
86
+
87
+ const resumed = await source.resume(result.snapshot, { host: { authorizeResume() {} } });
88
+ if (resumed.status !== "completed" || resumed.output.kind !== "count" || resumed.output.count !== 3)
89
+ throw new Error("Resume did not restore the counter's result.");
90
+ console.log(
91
+ `${result.output.count} open invoices. The next turn belongs to ${result.activeAgent.id}.`,
92
+ );
@@ -0,0 +1,127 @@
1
+ import type { Provider } from "@providerkit/core";
2
+ import { defineAgent, subagentTool } from "../src/index.ts";
3
+
4
+ // Offline example. This provider supplies fixed responses and makes no network calls.
5
+ const provider: Provider = {
6
+ id: "offline",
7
+ model: "example",
8
+ async *createStream(messages, tools) {
9
+ const coordinating = tools?.some((tool) => tool.name === "create_helpers");
10
+ const results = messages.findLast((message) => message.role === "tool");
11
+ if (coordinating && !results) {
12
+ yield {
13
+ type: "delta",
14
+ toolCalls: [
15
+ {
16
+ index: 0,
17
+ id: "helpers",
18
+ name: "create_helpers",
19
+ arguments: JSON.stringify({
20
+ agents: [
21
+ {
22
+ name: "reads",
23
+ task: "Explain how an index speeds up a search.",
24
+ instructions: "Use one short sentence.",
25
+ fork: true,
26
+ },
27
+ {
28
+ name: "writes",
29
+ task: "Explain why an index can slow down a write.",
30
+ instructions: "Use one short sentence.",
31
+ },
32
+ ],
33
+ }),
34
+ },
35
+ ],
36
+ };
37
+ yield { type: "finish", finishReason: "tool_calls" };
38
+ return;
39
+ }
40
+ if (
41
+ coordinating &&
42
+ results &&
43
+ messages.filter((message) => message.role === "tool").length === 1
44
+ ) {
45
+ const output: unknown = JSON.parse(results.content);
46
+ const first: unknown = Array.isArray(output) ? output[0] : undefined;
47
+ if (
48
+ !first ||
49
+ typeof first !== "object" ||
50
+ !("helperId" in first) ||
51
+ typeof first.helperId !== "string"
52
+ )
53
+ throw new Error("The helper did not return an identity.");
54
+ yield {
55
+ type: "delta",
56
+ toolCalls: [
57
+ {
58
+ index: 0,
59
+ id: "followup",
60
+ name: "create_helpers",
61
+ arguments: JSON.stringify({
62
+ agents: [
63
+ { name: "reads", continues: first.helperId, task: "Give one search example." },
64
+ ],
65
+ }),
66
+ },
67
+ ],
68
+ };
69
+ yield { type: "finish", finishReason: "tool_calls" };
70
+ return;
71
+ }
72
+ yield {
73
+ type: "delta",
74
+ content: coordinating
75
+ ? "An index helps a search find rows. A write has to update the index too."
76
+ : String(messages.at(-1)?.content).includes("search")
77
+ ? "An index points to matching rows without reading every row."
78
+ : "A write must update both the row and its index.",
79
+ };
80
+ yield { type: "finish", finishReason: "stop" };
81
+ },
82
+ };
83
+
84
+ const helper = defineAgent({
85
+ id: "helper",
86
+ version: "1",
87
+ instructions: "Answer only the task you receive.",
88
+ provider,
89
+ });
90
+ const explainer = defineAgent({
91
+ id: "explainer",
92
+ version: "1",
93
+ instructions: "Ask helpers about reads and writes, then combine their answers.",
94
+ provider,
95
+ tools: [
96
+ subagentTool({
97
+ name: "create_helpers",
98
+ description: "Start helpers for separate parts of the question.",
99
+ agent: helper,
100
+ followUp: true,
101
+ fork: {
102
+ identity: "public-example-history-1",
103
+ maxMessages: 2,
104
+ maxBytes: 2_000,
105
+ // This offline example contains only a public question. A real host checks its data.
106
+ select: (messages) => messages.map((_, index) => index).slice(-2),
107
+ },
108
+ }),
109
+ ],
110
+ });
111
+
112
+ const result = await explainer.run("When does a database index help?", {
113
+ // No external resources exist in this example. Production hosts check the owner and lease here.
114
+ host: { beforeTool() {} },
115
+ });
116
+ if (result.status !== "completed") throw new Error(`The example ended with ${result.status}.`);
117
+ if (result.snapshot.delegations[0]?.children.length !== 2) throw new Error("Expected two helpers.");
118
+ const original = result.snapshot.delegations[0]?.children[0]?.snapshot;
119
+ const followup = result.snapshot.delegations[1]?.children[0]?.snapshot;
120
+ if (
121
+ original?.kind !== "agent" ||
122
+ followup?.kind !== "agent" ||
123
+ !followup.subagent ||
124
+ followup.subagent.previousRunId !== original.runId
125
+ )
126
+ throw new Error("Expected a follow-up to the first helper.");
127
+ console.log(result.output);
@@ -0,0 +1,74 @@
1
+ import assert from "node:assert/strict";
2
+ import type { AgentHost } from "../src/types.ts";
3
+ import { defineAgent } from "../src/run.ts";
4
+ import { defineWorkflow } from "../src/workflow.ts";
5
+ import { isRecord } from "../src/snapshot.ts";
6
+
7
+ const writer = defineAgent({
8
+ id: "offline-writer",
9
+ version: "1",
10
+ instructions: "Write a short draft.",
11
+ provider: {
12
+ id: "offline",
13
+ model: "fixture",
14
+ async *createStream() {
15
+ yield {
16
+ type: "delta",
17
+ content: "An index helps a database find rows.",
18
+ finishReason: "stop",
19
+ };
20
+ },
21
+ },
22
+ });
23
+ const report = defineWorkflow({
24
+ id: "report",
25
+ version: "1",
26
+ input: {
27
+ schema: { type: "object", properties: { topic: { type: "string" } }, required: ["topic"] },
28
+ validate(raw) {
29
+ if (!isRecord(raw) || typeof raw.topic !== "string") throw new TypeError("Provide a topic.");
30
+ return { topic: raw.topic };
31
+ },
32
+ },
33
+ agents: [writer],
34
+ async run({ topic }, ctx) {
35
+ const draft = await ctx.agent("draft", writer, topic);
36
+ if (draft.status !== "completed") throw new Error("The writer did not finish.");
37
+ const title = await ctx.ask(
38
+ { key: "title", message: "What title should this use?" },
39
+ (answer) => {
40
+ if (!answer.text) throw new TypeError("Provide a title.");
41
+ return answer.text;
42
+ },
43
+ );
44
+ return ctx.step("format", () => `${title}\n${draft.output}`, {
45
+ input: { title, draft: draft.output },
46
+ });
47
+ },
48
+ });
49
+ // Fixture authority only. A real host checks authenticated ownership and its current lease.
50
+ const host = {
51
+ authorizeResume() {},
52
+ beforeTool() {},
53
+ beforeStep() {},
54
+ prepareRequest: () => ({
55
+ scope: {
56
+ actorId: "fixture",
57
+ resource: { id: "report", version: "1" },
58
+ expiresAt: Date.now() + 60_000,
59
+ },
60
+ }),
61
+ resolveRequest(_request, evidence) {
62
+ if (evidence !== "offline-fixture-claim") throw new Error("Unknown fixture evidence.");
63
+ return { type: "answer", answer: { text: "Database indexes" } };
64
+ },
65
+ } satisfies AgentHost;
66
+ const waiting = await report.run({ topic: "Database indexes" }, { host });
67
+ assert.equal(waiting.status, "suspended");
68
+ if (waiting.status !== "suspended" || !waiting.requests[0]) throw new Error("Missing question.");
69
+ const done = await report.resume(JSON.parse(JSON.stringify(waiting.snapshot)), {
70
+ host,
71
+ answers: { [waiting.requests[0].id]: "offline-fixture-claim" },
72
+ });
73
+ assert.equal(done.status, "completed");
74
+ if (done.status === "completed") console.log(done.output);