eve 0.90.0 → 0.91.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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
|
@@ -3,13 +3,13 @@ title: "Team Playbooks"
|
|
|
3
3
|
description: "Part 6 of the Build an Agent tutorial. Load the caller's team playbook with a dynamic skill keyed on the principal."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
The glossary from [Step 5](./remember-definitions) is per-session. But your teams have standing analysis conventions
|
|
6
|
+
The glossary from [Step 5](./remember-definitions) is per-session. But your teams have standing analysis conventions: Growth groups revenue by date, and Finance reconciles customer totals. One team's conventions shouldn't reach another team, so load the playbook for whoever is asking.
|
|
7
7
|
|
|
8
|
-
A skill is an on-demand procedure
|
|
8
|
+
A skill is an on-demand procedure the model loads with `eve__skill({ name })` only when a turn needs it. A dynamic skill is decided at runtime: a `defineDynamic` function reads the session and returns a `defineSkill` or `null`. Here the signed-in caller in `ctx.session.auth` decides which playbook is available. eve calls this signed-in identity the principal.
|
|
9
9
|
|
|
10
10
|
## A playbook per principal
|
|
11
11
|
|
|
12
|
-
`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the
|
|
12
|
+
`ctx.session.auth.current` holds the most recent caller, or `null` if there isn't one. Its `attributes` are the values your auth code added, including the team. Select the team, then return that team's playbook as a skill:
|
|
13
13
|
|
|
14
14
|
```ts title="agent/skills/team-playbook.ts"
|
|
15
15
|
import { defineDynamic, defineSkill } from "eve/skills";
|
|
@@ -44,17 +44,17 @@ export default defineDynamic((ctx) => {
|
|
|
44
44
|
});
|
|
45
45
|
```
|
|
46
46
|
|
|
47
|
-
The function
|
|
47
|
+
The function runs before each model call, so a later caller change updates the playbook. A caller with no team gets `null` and no playbook.
|
|
48
48
|
|
|
49
49
|
## See it route
|
|
50
50
|
|
|
51
|
-
|
|
51
|
+
Your auth code adds the team in [Step 8](./ship-it). Until then `ctx.session.auth.current` has no `team`, so the function returns `null` and no playbook loads. To check the routing now, add a team in local dev. Add a dev-only entry to `agent/channels/eve.ts` ahead of `localDev()`, and remove it before Step 8 wires real auth:
|
|
52
52
|
|
|
53
53
|
```ts title="agent/channels/eve.ts"
|
|
54
54
|
import { eveChannel } from "eve/channels/eve";
|
|
55
55
|
import { localDev, placeholderAuth, vercelOidc, type AuthFn } from "eve/channels/auth";
|
|
56
56
|
|
|
57
|
-
// Dev-only:
|
|
57
|
+
// Dev-only: add a team so Step 6's playbook has something to select.
|
|
58
58
|
// Remove before Step 8.
|
|
59
59
|
const devTeam: AuthFn<Request> = () =>
|
|
60
60
|
process.env.NODE_ENV === "production"
|
|
@@ -71,11 +71,11 @@ export default eveChannel({
|
|
|
71
71
|
});
|
|
72
72
|
```
|
|
73
73
|
|
|
74
|
-
Restart with `npm run dev` and ask "Summarize May 2026 revenue using our team's playbook." The model loads the skill with `eve__skill
|
|
74
|
+
Restart with `npm run dev` and ask "Summarize May 2026 revenue using our team's playbook." The model loads the skill with `eve__skill` and queries the sample data. It applies Growth's daily and plan groupings. Switch `team` to `"finance"`, restart, and ask again. The same question uses Finance's reconciliation rules.
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
The team comes from auth, not from the message, so one team can't get another team's playbook by asking for it.
|
|
77
77
|
|
|
78
|
-
The same `defineDynamic` form
|
|
78
|
+
The same `defineDynamic` form also works for dynamic tools and instructions. For details, see [Dynamic capabilities](../guides/dynamic-capabilities).
|
|
79
79
|
|
|
80
80
|
→ Next: [Guard the spend](./guard-the-spend)
|
|
81
81
|
|
package/docs/use-cases.mdx
CHANGED
|
@@ -3,7 +3,7 @@ title: "Use Cases"
|
|
|
3
3
|
description: "The two most common use cases for eve are business agents that work for your own company and agents you ship to customers as a product."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
eve
|
|
6
|
+
eve's two most common use cases are business agents for your own company and agents you ship to customers as a product.
|
|
7
7
|
|
|
8
8
|
<UseCaseSummaries>
|
|
9
9
|
<UseCaseSummary
|
|
@@ -103,8 +103,8 @@ An eve agent lives in [your repository](/docs/concepts/project-structure), so it
|
|
|
103
103
|
href="/docs/evals/overview"
|
|
104
104
|
link="Evals"
|
|
105
105
|
>
|
|
106
|
-
Evals
|
|
107
|
-
|
|
106
|
+
Evals run the agent through real turns and score the result with code checks or a model judge.
|
|
107
|
+
They catch regressions when a prompt, tool, or model changes.
|
|
108
108
|
</Capability>
|
|
109
109
|
<Capability
|
|
110
110
|
icon="tools"
|
|
@@ -114,7 +114,8 @@ An eve agent lives in [your repository](/docs/concepts/project-structure), so it
|
|
|
114
114
|
>
|
|
115
115
|
Tools are typed TypeScript functions the model chooses when to call. When a process must run the
|
|
116
116
|
same way every time, use a workflow tool instead. Its code fixes the order of steps, calls
|
|
117
|
-
subagents exactly where you say, and waits
|
|
117
|
+
subagents exactly where you say, and waits for approvals or webhooks between steps, even across
|
|
118
|
+
restarts.
|
|
118
119
|
</Capability>
|
|
119
120
|
<Capability
|
|
120
121
|
icon="sandbox"
|
|
@@ -131,14 +132,15 @@ An eve agent lives in [your repository](/docs/concepts/project-structure), so it
|
|
|
131
132
|
href="/docs/human-in-the-loop"
|
|
132
133
|
link="Human-in-the-loop"
|
|
133
134
|
>
|
|
134
|
-
Sessions pause while an approval is pending and resume
|
|
135
|
-
model can auto-approve routine tool calls.
|
|
135
|
+
Sessions pause while an approval is pending and resume when it resolves, even after a redeploy.
|
|
136
|
+
A decision model can auto-approve routine tool calls.
|
|
136
137
|
</Capability>
|
|
137
138
|
</Capabilities>
|
|
138
139
|
|
|
139
140
|
## Agent as a Service (AaaS)
|
|
140
141
|
|
|
141
|
-
In AaaS, the agent is the product. One multi-tenant deployment serves many customers
|
|
142
|
+
In AaaS, the agent is the product. One multi-tenant deployment serves many customers over long stretches of time. It must keep every user's sessions running over time and keep each tenant's data and identity
|
|
143
|
+
separate.
|
|
142
144
|
|
|
143
145
|
<TemplateCards>
|
|
144
146
|
<TemplateCard title="Web chat" template="eve-chat-template">
|
|
@@ -149,8 +151,8 @@ In AaaS, the agent is the product. One multi-tenant deployment serves many custo
|
|
|
149
151
|
browser automation.
|
|
150
152
|
</TemplateCard>
|
|
151
153
|
<TemplateCard title="Voice agent" template="eve-voice-template">
|
|
152
|
-
Users talk to the agent in the browser while it runs tools, asks for approvals, and keeps
|
|
153
|
-
|
|
154
|
+
Users talk to the agent in the browser while it runs tools, asks for approvals, and keeps state
|
|
155
|
+
that survives restarts.
|
|
154
156
|
</TemplateCard>
|
|
155
157
|
</TemplateCards>
|
|
156
158
|
|
|
@@ -200,8 +202,8 @@ Each end user gets their own [sessions](/docs/concepts/sessions-runs-and-streami
|
|
|
200
202
|
href="/docs/guides/decide"
|
|
201
203
|
link="Model selection"
|
|
202
204
|
>
|
|
203
|
-
Pick models per user, tenant, or feature
|
|
204
|
-
|
|
205
|
+
Pick models per user, tenant, or feature to balance cost, latency, and quality. A decision model
|
|
206
|
+
can also choose from your allowlist.
|
|
205
207
|
</Capability>
|
|
206
208
|
<Capability
|
|
207
209
|
icon="durability"
|
package/package.json
CHANGED
|
@@ -1,96 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: "Migrate Instrumentation"
|
|
3
|
-
description: "Move a single instrumentation.ts configuration into lifecycle instrumentation and OpenTelemetry destinations."
|
|
4
|
-
url: "/observability/instrumentation-migration"
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
Replace `agent/instrumentation.ts` with path-named files under
|
|
8
|
-
`agent/instrumentation/`. Remove
|
|
9
|
-
`experimental.instrumentationProviders` from `agent.ts`; instrumentation
|
|
10
|
-
discovery is now always enabled.
|
|
11
|
-
|
|
12
|
-
## Preserve metadata-only capture
|
|
13
|
-
|
|
14
|
-
In the removed API, omitted `recordInputs` and `recordOutputs` settings both
|
|
15
|
-
defaulted to `false`. Once an OpenTelemetry destination is present, the new
|
|
16
|
-
default includes content during development and for public conversations.
|
|
17
|
-
|
|
18
|
-
Add `agent/instrumentation/otel.ts` with an explicit metadata-only policy
|
|
19
|
-
before moving exporters:
|
|
20
|
-
|
|
21
|
-
```ts title="agent/instrumentation/otel.ts"
|
|
22
|
-
import { otel } from "eve/instrumentation/otel";
|
|
23
|
-
|
|
24
|
-
export default otel({
|
|
25
|
-
functionId: "support-agent",
|
|
26
|
-
traceChannelRequests: true,
|
|
27
|
-
tracePolicy: () => ({
|
|
28
|
-
emit: true,
|
|
29
|
-
recordInputs: false,
|
|
30
|
-
recordOutputs: false,
|
|
31
|
-
}),
|
|
32
|
-
});
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
After verifying each destination's retention and access controls, widen
|
|
36
|
-
`recordInputs` or `recordOutputs` deliberately if needed.
|
|
37
|
-
|
|
38
|
-
## Move an OpenTelemetry exporter
|
|
39
|
-
|
|
40
|
-
Move each exporter into its own destination file and replace startup
|
|
41
|
-
`registerOTel(...)` calls with `otelIntegration(...)`. Install `@vercel/otel`
|
|
42
|
-
if the exporter comes from that package:
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
pnpm add @vercel/otel
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
```ts title="agent/instrumentation/honeycomb.ts"
|
|
49
|
-
import { OTLPHttpProtoTraceExporter } from "@vercel/otel";
|
|
50
|
-
import { otelIntegration } from "eve/instrumentation/otel";
|
|
51
|
-
|
|
52
|
-
export default otelIntegration({
|
|
53
|
-
exportPolicy: {
|
|
54
|
-
span: () => ({ redact: true, inputs: true, outputs: true }),
|
|
55
|
-
},
|
|
56
|
-
traceExporter: new OTLPHttpProtoTraceExporter({
|
|
57
|
-
url: "https://api.honeycomb.io/v1/traces",
|
|
58
|
-
headers: {
|
|
59
|
-
"x-honeycomb-team": process.env.HONEYCOMB_API_KEY!,
|
|
60
|
-
},
|
|
61
|
-
}),
|
|
62
|
-
});
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
The destination policy preserves metadata-only export even if the shared
|
|
66
|
-
OpenTelemetry policy is widened later. Add another file for each additional
|
|
67
|
-
destination; eve combines them into one pipeline.
|
|
68
|
-
|
|
69
|
-
## Move runtime context and lifecycle events
|
|
70
|
-
|
|
71
|
-
Use this mapping when splitting the old definition:
|
|
72
|
-
|
|
73
|
-
| `agent/instrumentation.ts` field | New location |
|
|
74
|
-
| -------------------------------- | -------------------------------------------- |
|
|
75
|
-
| `setup` with `registerOTel` | One `otelIntegration()` file per destination |
|
|
76
|
-
| `functionId` | `otel({ functionId })` |
|
|
77
|
-
| `recordInputs`, `recordOutputs` | `otel({ tracePolicy })` |
|
|
78
|
-
| `traceChannelRequests` | `otel({ traceChannelRequests })` |
|
|
79
|
-
| `events["step.started"]` | `otelIntegration({ runtimeContext })` |
|
|
80
|
-
|
|
81
|
-
Move `events["step.started"]` to the destination that needs those attributes;
|
|
82
|
-
see [Add runtime context](/docs/observability/otel#add-runtime-context). For
|
|
83
|
-
eve lifecycle events, create a separate file with `defineInstrumentation(...)`;
|
|
84
|
-
see
|
|
85
|
-
[Instrumentation](/docs/observability/instrumentation).
|
|
86
|
-
|
|
87
|
-
## Verify the migration
|
|
88
|
-
|
|
89
|
-
Run `eve build`. A remaining `agent/instrumentation.ts` fails the build with a
|
|
90
|
-
message directing you to the instrumentation directory.
|
|
91
|
-
|
|
92
|
-
New eve deployments automatically sample 100% of requests. Existing Vercel
|
|
93
|
-
deployments need project sampling configured before you verify them. See
|
|
94
|
-
[Enable tracing on Vercel](/docs/observability/agent-runs#enable-tracing-on-vercel).
|
|
95
|
-
|
|
96
|
-
Then run the agent and verify each destination independently.
|
|
@@ -1,218 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: "Upgrade to Tasks"
|
|
3
|
-
description: "Move workflow tools, agent calls, clients, hooks, and evals from background tasks to tasks."
|
|
4
|
-
url: /tools/tasks-upgrade
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
> This guide names session events as they were before stream version 27. To move those events to
|
|
8
|
-
> v27 facts, see [Upgrade to v27 session events](/docs/concepts/upgrade-to-v27-events).
|
|
9
|
-
|
|
10
|
-
This release replaces background tasks with [tasks](/docs/tools/tasks). Every change below breaks
|
|
11
|
-
the previous API. Work through the sections that apply to your agent. A workflow tool that uses
|
|
12
|
-
none of `execution: "background"`, `dismissible`, or `ctx.agent` keeps its code: `execute(input,
|
|
13
|
-
ctx)` keeps its signature, and `ctx.abortSignal` and `ctx.callId` are where they were. One behavior
|
|
14
|
-
changes for every `execute` tool: a steering message now aborts its `ctx.abortSignal`. See
|
|
15
|
-
[Drop `dismissible`](#drop-dismissible-a-new-message-stops-an-execute-call).
|
|
16
|
-
Type-checking flags most of the code changes, such as the removed `execution` and `dismissible`
|
|
17
|
-
options and the old `ctx.agent` call.
|
|
18
|
-
|
|
19
|
-
## Replace `execution: "background"` with `task(input, ctx)`
|
|
20
|
-
|
|
21
|
-
Rename `execute` to `task` and remove `execution`. The body doesn't change:
|
|
22
|
-
|
|
23
|
-
```diff
|
|
24
|
-
export default defineWorkflowTool({
|
|
25
|
-
description: "Deploy a service.",
|
|
26
|
-
inputSchema: z.object({ service: z.string() }),
|
|
27
|
-
- execution: "background",
|
|
28
|
-
- async execute({ service }, ctx) {
|
|
29
|
-
+ async task({ service }, ctx) {
|
|
30
|
-
"use workflow";
|
|
31
|
-
return await deploy(service, ctx.abortSignal);
|
|
32
|
-
},
|
|
33
|
-
});
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
`defineWorkflowTool` rejects `execution` with
|
|
37
|
-
`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.` A
|
|
38
|
-
`task` body gets the same `WorkflowToolContext` as an `execute` body, and steering never aborts a
|
|
39
|
-
task's `abortSignal`. An `execute` tool is an ordinary tool call: the turn waits for its result. See
|
|
40
|
-
[Choose how a call runs](/docs/tools/tasks#choose-how-a-call-runs).
|
|
41
|
-
|
|
42
|
-
A tool that the model should be able to send more input while it works, such as a plan it revises
|
|
43
|
-
on request, defines [`serve(receive, ctx)`](/docs/tools/workflows#resumable-tasks-serve) instead.
|
|
44
|
-
|
|
45
|
-
## Drop `dismissible`: a new message stops an `execute` call
|
|
46
|
-
|
|
47
|
-
`ctx.ask` no longer accepts `dismissible`. A steering message now aborts the `ctx.abortSignal` of
|
|
48
|
-
each `execute` call the turn waits on, which withdraws every question the call asked, as
|
|
49
|
-
`dismissible: true` did:
|
|
50
|
-
|
|
51
|
-
```diff
|
|
52
|
-
-const answer = await ctx.ask({ prompt, dismissible: true });
|
|
53
|
-
+const answer = await ctx.ask({ prompt });
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
To keep a question open through new messages, ask it from a
|
|
57
|
-
[`task`](#replace-execution-background-with-taskinput-ctx) instead. Other work that
|
|
58
|
-
receives `ctx.abortSignal`, such as a step or a `ctx.agent` send, stops too. The call settles with
|
|
59
|
-
what the body returns, or with `{ interrupted: true }` if the body rejects, and the model reads the
|
|
60
|
-
message next.
|
|
61
|
-
|
|
62
|
-
A withdrawn question resolves as `{ status: "cancelled" }` instead of `dismissed`, and the
|
|
63
|
-
`input.resolved` outcome `"dismissed"` is now `"cancelled"`. Update clients and channels that
|
|
64
|
-
match on the old value. See [Pass signals to the work](/docs/tools/tasks#pass-signals-to-the-work).
|
|
65
|
-
|
|
66
|
-
## Open agent sessions with `ctx.agent(name)`
|
|
67
|
-
|
|
68
|
-
`ctx.agent(name, { message, agentId })`, which returned the agent's output, is now
|
|
69
|
-
`ctx.agent(name)`, which returns a session. Send a message and read the turn's result:
|
|
70
|
-
|
|
71
|
-
```diff
|
|
72
|
-
-const review = await ctx.agent("reviewer", { message: plan });
|
|
73
|
-
+const response = await ctx.agent("reviewer").send(plan, { signal: ctx.abortSignal });
|
|
74
|
-
+const { message: review, status } = await response.result();
|
|
75
|
-
+if (status === "failed") throw new Error("The review failed.");
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
`agentId` is removed. Each `ctx.agent(name)` call returns a new session, and later `send` calls on
|
|
79
|
-
the same handle continue its conversation until the workflow run finishes. See
|
|
80
|
-
[Delegate work](/docs/tools/workflows#delegate-work-ctxagent). The `workflow` tool's generated
|
|
81
|
-
programs keep their `ctx.agent(name, { message, outputSchema? })` capability.
|
|
82
|
-
|
|
83
|
-
## Continue agents by `taskId`
|
|
84
|
-
|
|
85
|
-
Every agent tool is now a `serve` tool, so every agent call is a resumable task. The model's agent
|
|
86
|
-
tools take `taskId` instead of `agentId`:
|
|
87
|
-
|
|
88
|
-
```diff
|
|
89
|
-
-{ "message": "Check the Q2 numbers too.", "agentId": "…" }
|
|
90
|
-
+{ "message": "Check the Q2 numbers too.", "taskId": "researcher-7k2m9q" }
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
An agent call returns a receipt at once, and the agent's reply arrives later in a `task.result`
|
|
94
|
-
message. Update instructions, prompts, and evals that mention `agentId` or expect the reply as
|
|
95
|
-
the tool result. `agentRouter()` and the `workflow` tool now run each call as a task too.
|
|
96
|
-
|
|
97
|
-
The removed codes `AGENT_BUSY`, `AGENT_MISMATCH`, `AGENT_UNREACHABLE`, and
|
|
98
|
-
`AGENT_INVOCATION_NOT_ADMITTED` have no replacement. A `taskId` that names no unfinished task of
|
|
99
|
-
that tool fails with `UNKNOWN_TASK`, and a call past the limit of 32 working tasks fails with
|
|
100
|
-
`TOO_MANY_TASKS`.
|
|
101
|
-
|
|
102
|
-
## Remove background delivery options
|
|
103
|
-
|
|
104
|
-
Results reach the model one way: a `task.result` message at a step boundary. Remove these:
|
|
105
|
-
|
|
106
|
-
- `taskDeliveryPolicy` and delivery cohorts.
|
|
107
|
-
- The `tasks` option of `session.cancel()`. `session.cancel()` now cancels the turn, the `execute`
|
|
108
|
-
calls it waits on, and every working task; it still accepts `turnId` and `signal`.
|
|
109
|
-
|
|
110
|
-
The model no longer sees `[Task state]` or `[Agents]` notes, prose task notifications,
|
|
111
|
-
`<eve-empty-delivery/>`, or result turns. A `[Tasks]` note lists its working and idle tasks
|
|
112
|
-
instead. The `BACKGROUND_TASK_FAILED` and `BACKGROUND_TASK_CANCELLED` codes are removed; a
|
|
113
|
-
failed task reports its error in `task.settled` and in its `task.result` block.
|
|
114
|
-
|
|
115
|
-
## Read task events instead of `subagent.*` events
|
|
116
|
-
|
|
117
|
-
The `subagent.called`, `subagent.started`, `subagent.completed`, and `subagent.event` events are
|
|
118
|
-
removed. Use these instead:
|
|
119
|
-
|
|
120
|
-
| Event | Replaces | Data |
|
|
121
|
-
| --------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
|
|
122
|
-
| `task.started` | `subagent.called` | `taskId`, `callId`, `turnId`, `name`, `kind` |
|
|
123
|
-
| `task.settled` | `subagent.completed` | `taskId`, `callId`, `turnId`, `name`, `kind`, `status`, and `output` or `error` unless cancelled |
|
|
124
|
-
| `agent.started` | `subagent.started` | `callId`, `turnId`, `taskId`, `name`, `sessionId`, `streamPath` |
|
|
125
|
-
|
|
126
|
-
Follow a child's own events, which `subagent.event` used to relay, on its stream:
|
|
127
|
-
`session.streamSubagent()` is now `session.agent(started).stream()`, and it takes the `agent.started` event.
|
|
128
|
-
|
|
129
|
-
```diff
|
|
130
|
-
for await (const event of session.stream()) {
|
|
131
|
-
- if (event.type !== "subagent.called") continue;
|
|
132
|
-
+ if (event.type !== "agent.started") continue;
|
|
133
|
-
- for await (const childEvent of session.streamSubagent(event)) {
|
|
134
|
-
+ for await (const childEvent of session.agent(event).stream()) {
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
Hooks subscribe the same way:
|
|
138
|
-
|
|
139
|
-
```diff
|
|
140
|
-
export default defineHook({
|
|
141
|
-
events: {
|
|
142
|
-
- async "subagent.completed"(event, ctx) {
|
|
143
|
-
+ async "task.settled"(event, ctx) {
|
|
144
|
-
+ if (event.data.status !== "completed") return;
|
|
145
|
-
```
|
|
146
|
-
|
|
147
|
-
The eval assertion `t.calledSubagent` is now `t.calledAgent(name, { status })` and reads call facts; see [Assertions](/docs/evals/assertions#the-matcher-mini-language).
|
|
148
|
-
|
|
149
|
-
## Handle open turns in clients
|
|
150
|
-
|
|
151
|
-
A turn doesn't end while tasks are working, so one turn can span a wait. The stream
|
|
152
|
-
reports each wait with the new `turn.waiting` event, which carries the open turn's `turnId`:
|
|
153
|
-
|
|
154
|
-
- **Held turns.** When the model ends its text while its tasks work, and when `eve__task_wait` has no
|
|
155
|
-
result yet, the stream emits `turn.waiting`. The next `step.started` for the same `turnId` means
|
|
156
|
-
the turn resumed. In a root session, the text before the wait completes as a normal
|
|
157
|
-
`message.completed`; in child sessions and a schedule's sessions, that step reports
|
|
158
|
-
`finishReason: "tool-calls"`.
|
|
159
|
-
- **Questions and sign-ins inside a call no longer end the turn.** Previously, a question or
|
|
160
|
-
sign-in from inside a running call, such as a workflow tool's `ctx.ask()`, `ask_question`, or a
|
|
161
|
-
subagent's question, emitted `turn.completed` and `session.waiting` in the middle of the turn.
|
|
162
|
-
It now emits `input.requested` or `authorization.required`, then `turn.waiting`, and the turn
|
|
163
|
-
resumes under the same `turnId` after the answer. The session you answer on emits
|
|
164
|
-
`input.resolved` for every question it routes an answer to. A sign-in or tool approval the
|
|
165
|
-
turn itself requests holds the turn the same way, with `turn.waiting` on `"input"`.
|
|
166
|
-
- **`turn.completed` comes only when the turn really ends,** and `session.waiting` always means
|
|
167
|
-
the turn has ended.
|
|
168
|
-
|
|
169
|
-
The TypeScript client's `send(...).result()` reads past `turn.waiting` and returns the final reply
|
|
170
|
-
of a held turn, not the text written before the wait. At `turn.waiting`, an unanswered input
|
|
171
|
-
request (a question, approval, or `session-limit` prompt) makes `result()` return
|
|
172
|
-
`status: "waiting"`; use `respond()` to answer it and continue reading the same turn.
|
|
173
|
-
A sign-in keeps the response attached while its authorization callback is pending. Render the
|
|
174
|
-
sign-in prompt from the live `authorization.required` event rather than waiting for `result()`.
|
|
175
|
-
A custom client that ends a response at `turn.completed` or
|
|
176
|
-
`session.waiting` mid-turn, or that shows the first completed message as the reply, should follow
|
|
177
|
-
the same rule. See [Aggregate a turn](/docs/guides/client/streaming#aggregate-a-turn).
|
|
178
|
-
|
|
179
|
-
Task results aren't stream events. Background task results used to appear as `message.received`
|
|
180
|
-
with `data.kind: "execution.background_task"`; `message.received` no longer has `kind`, and a task
|
|
181
|
-
result reaches only the model. Read each call's outcome from `task.settled` instead.
|
|
182
|
-
|
|
183
|
-
The message stream version is now 26. The TypeScript client accepts versions 21 through 26. A
|
|
184
|
-
client that accepts only versions up to 25 fails the stream with an unsupported-version error. See
|
|
185
|
-
[Turns wait for their tasks](/docs/tools/tasks#turns-wait-for-their-tasks).
|
|
186
|
-
|
|
187
|
-
## Upgrade remote agents before their callers
|
|
188
|
-
|
|
189
|
-
Later eve releases no longer serve protocol-1 callers or accept protocol-1 remote agents. Upgrade
|
|
190
|
-
every caller and remote agent past 0.68 before you upgrade any of them past that later release.
|
|
191
|
-
The rest of this section describes this release.
|
|
192
|
-
|
|
193
|
-
The remote agent protocol is now version 2. Deploy each [remote agent](/docs/guides/remote-agents)
|
|
194
|
-
before the deployments that call it. A remote agent on this release still serves callers on eve 0.66
|
|
195
|
-
through 0.68, which speak protocol 1. It runs their turns, sends each result to their callback, and
|
|
196
|
-
accepts their follow-up and reset requests. It also sends the remote agent's tool approvals and
|
|
197
|
-
sign-in requests to the caller, and accepts the caller's answers, the same way a 0.66–0.68 remote
|
|
198
|
-
agent does. As in 0.66–0.68, this covers agents the caller's model calls, which run as background
|
|
199
|
-
tasks. When the caller's own workflow tool code calls an agent, its approvals and sign-in requests
|
|
200
|
-
stay on the remote agent's channel.
|
|
201
|
-
|
|
202
|
-
Two things differ from a remote agent on the caller's own release:
|
|
203
|
-
|
|
204
|
-
- The caller's channel doesn't show the remote agent's live tool activity nested under the call.
|
|
205
|
-
- `ctx.ask()` in the remote agent returns `unavailable`, because protocol-1 callers don't grant the
|
|
206
|
-
remote agent input. That's unchanged from 0.66–0.68.
|
|
207
|
-
|
|
208
|
-
Each protocol-1 create logs `serving a remote agent protocol 1 caller` with the caller's origin.
|
|
209
|
-
|
|
210
|
-
Upgrade a caller after every remote agent it calls. A caller on this release accepts a protocol-1
|
|
211
|
-
remote agent's results and failures, but that remote agent's approvals and sign-in requests don't
|
|
212
|
-
reach the caller. Any other protocol mismatch fails the call at start, with an error that names
|
|
213
|
-
both versions.
|
|
214
|
-
|
|
215
|
-
Upgrade a caller and its remote agents together, or let the remote agents' in-flight work finish
|
|
216
|
-
first. A remote agent's callbacks go to the caller's current production deployment, so approvals,
|
|
217
|
-
questions, and sign-ins that an earlier remote agent sends after the caller upgrades are rejected
|
|
218
|
-
and never reach the caller. The caller's own sessions stay on the deployment that started them.
|