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
package/docs/tools/workflows.mdx
CHANGED
|
@@ -4,27 +4,29 @@ description: "Define durable workflow tools that wait for people, webhooks, or t
|
|
|
4
4
|
url: /tools/workflows
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
A workflow tool is a
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
`
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
7
|
+
A workflow tool is a tool whose calls can wait for a person, a webhook, or a timer without holding
|
|
8
|
+
compute. Define one with `defineWorkflowTool` from `eve/tools` under `agent/tools/`. The model sees
|
|
9
|
+
it under its path-derived name, such as `deploy`.
|
|
10
|
+
|
|
11
|
+
Use a workflow tool when a call must wait for input, delegate work to subagents, or run retryable
|
|
12
|
+
steps over a long period. Each call starts a Workflow run that survives restarts. For a tool that
|
|
13
|
+
returns in one step, use [`defineTool`](/docs/tools) instead.
|
|
14
|
+
|
|
15
|
+
A workflow tool defines exactly one entry point, which decides how its calls run:
|
|
16
|
+
|
|
17
|
+
| Entry point | How a call runs |
|
|
18
|
+
| --------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| `execute(input, ctx)` | The turn waits until the workflow finishes, then gets its output as the tool result. Waits hold no compute. |
|
|
20
|
+
| `task(input, ctx)` | A [task](#run-calls-as-tasks-task): the model gets a receipt at once, and the result arrives later. |
|
|
21
|
+
| `serve(receive, ctx)` | A [resumable task](#resumable-tasks-serve) that the model can send more calls by its `taskId`. |
|
|
22
|
+
|
|
23
|
+
See [Tasks](/docs/tools/tasks) for choosing between them and for what the model sees while tasks
|
|
24
|
+
work.
|
|
25
|
+
|
|
26
|
+
Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`,
|
|
27
|
+
`createHook`, `createWebhook`, `sleep`, retries, and replay. eve adds `ctx.ask` to ask a person a
|
|
28
|
+
question and `ctx.agent` to open a session with another agent. `ctx.agents` lists the agents the
|
|
29
|
+
call can open.
|
|
28
30
|
|
|
29
31
|
## Define a workflow tool
|
|
30
32
|
|
|
@@ -66,215 +68,93 @@ async function applyDeploy(plan: DeployPlan) {
|
|
|
66
68
|
}
|
|
67
69
|
```
|
|
68
70
|
|
|
69
|
-
The
|
|
70
|
-
|
|
71
|
+
The turn waits while the person reads the plan. When they answer, minutes or days later, the run
|
|
72
|
+
continues, deploys, and returns one tool result.
|
|
71
73
|
|
|
72
74
|
### Rules
|
|
73
75
|
|
|
74
|
-
-
|
|
75
|
-
`
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
has one.
|
|
76
|
+
- Default-export `defineWorkflowTool({ ... })` with exactly one entry point: `execute`, `task`, or
|
|
77
|
+
`serve`. Defining none, or more than one, throws when the tool is defined.
|
|
78
|
+
- Write the entry point inline, or reference a top-level `async function` in the same module or an
|
|
79
|
+
imported application module. `execute` and `task` can be async generators; `serve` can't.
|
|
80
|
+
- Start the entry point with `"use workflow"`. A missing directive is a build error, even if another
|
|
81
|
+
function in the module has one.
|
|
81
82
|
- `"use step"` marks a top-level `async function` in the tool module, or any module it imports, as a
|
|
82
|
-
step.
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
`eve/workflow/api` in routes or steps, not
|
|
87
|
-
|
|
88
|
-
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
`
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
`
|
|
112
|
-
|
|
113
|
-
workflow and step modules from the shared root package, such as a root `lib/` directory.
|
|
114
|
-
eve includes only workflow and step modules reachable from the agent's runtime modules.
|
|
115
|
-
Unrelated workflows in the host application stay outside the agent bundle. An unresolved
|
|
116
|
-
workflow import fails the build with the missing import in the error.
|
|
83
|
+
step. The workflow body replays and must stay deterministic, so put side effects, clocks,
|
|
84
|
+
randomness, `process.env`, and Node.js APIs in steps. Keep values you need after a wait in local
|
|
85
|
+
variables in the body.
|
|
86
|
+
- Import durable primitives such as `createHook`, `sleep`, and `FatalError` from `eve/workflow` in
|
|
87
|
+
the body. Call `start`, `getRun`, and `resumeHook` from `eve/workflow/api` in routes or steps, not
|
|
88
|
+
in the body. Both use eve's bundled Workflow SDK, so your app needs no `workflow` dependency. See
|
|
89
|
+
[Workflow imports](#workflow-imports).
|
|
90
|
+
- The tool's input must be a JSON object.
|
|
91
|
+
- Workflow bodies are for static tools under `agent/tools/`, not tools a `defineDynamic` function
|
|
92
|
+
returns. `"use workflow"` in `defineTool`, a bare tool object, a channel handler, or a schedule
|
|
93
|
+
handler fails the build. To start a session from a channel or schedule, use the
|
|
94
|
+
[channel operations](/docs/channels/custom#channel-operations-and-session-handles) or
|
|
95
|
+
[schedule handler](/docs/schedules#handler-form-run) APIs.
|
|
96
|
+
- Workflow imports resolve `paths` aliases from `tsconfig.json` or `jsconfig.json`, including in a
|
|
97
|
+
workspace package. An [agent workspace](/docs/concepts/project-structure#several-root-agents)
|
|
98
|
+
member can import workflow and step modules from the shared root package, such as `lib/`. An
|
|
99
|
+
unresolved workflow import fails the build and names the missing import.
|
|
100
|
+
|
|
101
|
+
The context depends on where your code runs:
|
|
102
|
+
|
|
103
|
+
| Where | Type | Members |
|
|
104
|
+
| ----------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
105
|
+
| `execute` or `task` body | `WorkflowToolContext` | `session`, `callId`, `toolName`, `abortSignal`, `channel`, `agent`, `agents`, `ask` |
|
|
106
|
+
| `serve` body | `WorkflowServeContext` | `session`, `toolName`, `channel`, `agent`, `agents`, `ask`, `reply`; each received call carries `callId` and `abortSignal` |
|
|
107
|
+
| `"use step"` helper that gets `ctx` | `WorkflowStepToolContext` | `session`, `callId`, `toolName`, `abortSignal`, `channel`, `getSandbox`, `getToken`, `requireAuth`, `to` |
|
|
108
|
+
|
|
109
|
+
Call `ctx.agent()` and `ctx.ask()` and read `ctx.agents` in the workflow body. Pass a step only the
|
|
110
|
+
serializable values it needs. Call `getSandbox`, `getToken`, `requireAuth`, and `to` in a step, because
|
|
111
|
+
the workflow body throws when it calls them. Ordinary tools, channel handlers, and schedule handlers
|
|
112
|
+
don't receive `agent`, `agents`, or `ask`. Import `WorkflowStepToolContext` from `eve/tools` to type
|
|
113
|
+
step helpers.
|
|
117
114
|
|
|
118
115
|
### Workflow imports
|
|
119
116
|
|
|
120
|
-
|
|
117
|
+
Import durable primitives from `eve/workflow`, and run and hook operations from `eve/workflow/api`:
|
|
121
118
|
|
|
122
119
|
```ts
|
|
123
120
|
import { createHook, sleep } from "eve/workflow";
|
|
124
121
|
import { resumeHook } from "eve/workflow/api";
|
|
125
122
|
```
|
|
126
123
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
- `getWorkflowMetadata()` returns the current run's `workflowName`, `workflowRunId`,
|
|
138
|
-
`workflowStartedAt`, and `url`.
|
|
139
|
-
- Throw `FatalError` to fail without retrying, or `RetryableError` with an optional
|
|
140
|
-
`{ retryAfter }` to retry a step.
|
|
141
|
-
|
|
142
|
-
Import `WorkflowHook`, `WorkflowHookOptions`, `WorkflowWebhook`, `WorkflowWebhookOptions`,
|
|
143
|
-
`WorkflowWebhookRequest`, and `WorkflowMetadata` from `eve/workflow` when you need explicit types.
|
|
144
|
-
|
|
145
|
-
`eve/workflow/api` exports:
|
|
146
|
-
|
|
147
|
-
- `start(workflow, args)` starts a `"use workflow"` function; omit `args` when it takes none. eve
|
|
148
|
-
routes the run to the agent's own workflow queue and deployment, so `start` takes no options.
|
|
149
|
-
- `start` and `getRun(runId)` return a `WorkflowRun<T>` with `runId`, `status` (a promise of
|
|
150
|
-
`WorkflowRunStatus`), `returnValue`, and `cancel()`.
|
|
151
|
-
- `resumeHook(token, payload)` delivers a payload to the hook with that token. Pass a
|
|
152
|
-
deterministic `token` to `createHook` when a route must find the hook later.
|
|
153
|
-
|
|
154
|
-
Bare `workflow` and `workflow/*` imports in application modules fail the build with an error
|
|
155
|
-
naming these entries. Only the exports listed above are public; other SDK subpaths, helpers, and
|
|
156
|
-
options are not supported by these entries. Existing `"types": ["eve/workflow-modules"]` tsconfig entries and reference
|
|
157
|
-
directives still resolve through 1.x, but the compatibility entry declares no ambient modules.
|
|
158
|
-
You can remove those references when updating your imports.
|
|
159
|
-
|
|
160
|
-
### Add a runtime-generated workflow tool
|
|
161
|
-
|
|
162
|
-
Create `agent/tools/workflow.ts` and export the provided `workflow` factory when the model should
|
|
163
|
-
supply the JavaScript program at runtime:
|
|
164
|
-
|
|
165
|
-
```ts title="agent/tools/workflow.ts"
|
|
166
|
-
import { workflow } from "eve/tools/workflow";
|
|
167
|
-
|
|
168
|
-
export default workflow({ maxSubagents: 20 });
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
The `workflow` tool runs each call as a [task](#run-calls-as-tasks-task), so the program's return
|
|
172
|
-
value reaches the model in a `task.result` message. The model supplies an async function body
|
|
173
|
-
through the tool's `js` input. Its only host capability is
|
|
174
|
-
`ctx.agent(name, { message, outputSchema? })`, which sends the message to a new session with that
|
|
175
|
-
agent and resolves to its reply, or to the structured value when `outputSchema` is set. This can invoke subagents configured with `tool: false` or hidden by a same-named `disableTool()` file. Include those path-derived names in the workflow tool description or agent instructions when the model writes the program. For example:
|
|
176
|
-
|
|
177
|
-
```js
|
|
178
|
-
const [triage, review] = await Promise.all([
|
|
179
|
-
ctx.agent("ticket-triage", { message: JSON.stringify(tickets) }),
|
|
180
|
-
ctx.agent("ticket-review", { message: JSON.stringify(tickets) }),
|
|
181
|
-
]);
|
|
182
|
-
return { triage, review };
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
`maxSubagents` defaults to `100` and must be an integer from `1` through `128`. The generated
|
|
186
|
-
program cannot access the workflow context, session state,
|
|
187
|
-
credentials, imports, or ordinary tools. Each call starts a new child session; a program cannot
|
|
188
|
-
continue a child from an earlier call. Agent authorization, questions, approvals, and cancellation
|
|
189
|
-
behave as they do for sessions an authored workflow tool opens with `ctx.agent`.
|
|
190
|
-
|
|
191
|
-
The sandbox resumes after every pending call in the current batch settles. `Promise.all` supports
|
|
192
|
-
fan-out followed by fan-in. The program must await every `ctx.agent` call before it returns. A call
|
|
193
|
-
that is still pending at that point, such as one that is never awaited or one that loses a
|
|
194
|
-
`Promise.race` or `Promise.any`, fails the workflow.
|
|
124
|
+
| Export | Entry | What it does |
|
|
125
|
+
| -------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
126
|
+
| `createHook<T>({ token?, metadata? })` | `eve/workflow` | Returns a `WorkflowHook<T>`. Await it for the next payload, or iterate it with `for await`. `metadata` is JSON stored with the hook. |
|
|
127
|
+
| `createWebhook({ respondWith? })` | `eve/workflow` | Returns a `WorkflowWebhook` whose `url` resumes it with the incoming `Request`. With `respondWith: "manual"`, answer each `WorkflowWebhookRequest` with `request.respondWith(response)`. |
|
|
128
|
+
| `sleep(duration)` | `eve/workflow` | Waits for a duration such as `"1h"` or a number of milliseconds, or until a `Date`. |
|
|
129
|
+
| `getWorkflowMetadata()` | `eve/workflow` | Returns the run's `workflowName`, `workflowRunId`, `workflowStartedAt`, and `url`. |
|
|
130
|
+
| `FatalError`, `RetryableError` | `eve/workflow` | Throw `FatalError` to fail without a retry. Throw `RetryableError`, with an optional `{ retryAfter }`, to retry a step. |
|
|
131
|
+
| `start(workflow, args)` | `eve/workflow/api` | Starts a `"use workflow"` function on the agent's own workflow queue and deployment. It takes no options; omit `args` when the function takes none. |
|
|
132
|
+
| `getRun(runId)` | `eve/workflow/api` | Returns a `WorkflowRun<T>` with `runId`, `status`, `returnValue`, and `cancel()`. `start` returns the same type. |
|
|
133
|
+
| `resumeHook(token, payload)` | `eve/workflow/api` | Sends a payload to the hook with that token. |
|
|
195
134
|
|
|
196
|
-
A
|
|
197
|
-
`WorkflowProgramAgentError` at that `ctx.agent` call, which the program can catch; the message
|
|
198
|
-
says which.
|
|
135
|
+
A hook's `token` resumes it. Pass a fixed `token` to `createHook` when a route must find the hook later. `await hook.getConflict()` registers the hook before you hand out its token, and resolves to the run that already holds the token, or `null`. Call `dispose()`, or declare the hook with `using`, to release the token.
|
|
199
136
|
|
|
200
|
-
|
|
201
|
-
so a `Date` becomes a string and functions and `undefined` members drop. A return value that
|
|
202
|
-
converts to nothing, such as `undefined`, becomes `null`. Each converted value may be up to 1 MiB of
|
|
203
|
-
JSON, each child reply up to 4 MiB of JSON, and the program source up to 256 KiB.
|
|
137
|
+
Import `WorkflowHook`, `WorkflowHookOptions`, `WorkflowWebhook`, `WorkflowWebhookOptions`, `WorkflowWebhookRequest`, and `WorkflowMetadata` from `eve/workflow` for explicit types.
|
|
204
138
|
|
|
205
|
-
|
|
206
|
-
Time spent waiting for child agents does not count toward either limit.
|
|
207
|
-
|
|
208
|
-
### Migrate from `experimental_workflow`
|
|
209
|
-
|
|
210
|
-
The experimental uppercase `Workflow` framework tool and its exports have been removed. Replace the
|
|
211
|
-
old sentinel:
|
|
212
|
-
|
|
213
|
-
```diff
|
|
214
|
-
-import { experimental_workflow } from "eve/tools/workflow";
|
|
215
|
-
-
|
|
216
|
-
-export default experimental_workflow({ maxSubagents: 20 });
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
with the lowercase factory:
|
|
220
|
-
|
|
221
|
-
```ts
|
|
222
|
-
import { workflow } from "eve/tools/workflow";
|
|
223
|
-
|
|
224
|
-
export default workflow({ maxSubagents: 20 });
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
The path gives the authored tool the model-facing name `workflow`. eve does not discover or inject
|
|
228
|
-
an agent catalog. Calls use the same target resolution, availability, and authorization checks as
|
|
229
|
-
`ctx.agent` in any other authored workflow tool.
|
|
230
|
-
|
|
231
|
-
### Migrate an authored workflow tool
|
|
232
|
-
|
|
233
|
-
Replace `defineTool` with `defineWorkflowTool`, keep the executor's `"use workflow"` directive,
|
|
234
|
-
and replace `agent(ctx, input)` and `ask(ctx, request)` with an agent session from
|
|
235
|
-
[`ctx.agent(name)`](#delegate-work-ctxagent) and `ctx.ask(request)`. The old `agent` and `ask`
|
|
236
|
-
helpers are not exported from `eve/workflow`; that entry exposes durable primitives instead.
|
|
237
|
-
Import `WorkflowToolContext`, `AgentSession`,
|
|
238
|
-
`ToolQuestion`, `ToolAskOptions`, and `ToolAnswer` from `eve/tools` when you
|
|
239
|
-
need explicit types.
|
|
240
|
-
|
|
241
|
-
`ctx.ask` no longer accepts `dismissible`, and its `dismissed` status is now `cancelled`. A
|
|
242
|
-
steering message withdraws a question an `execute` call asks, so drop the option. To keep a
|
|
243
|
-
question open while the conversation continues, ask it from a [`task`](#run-calls-as-tasks-task).
|
|
244
|
-
|
|
245
|
-
```diff
|
|
246
|
-
-const answer = await ctx.ask({ prompt, dismissible: true });
|
|
247
|
-
+const answer = await ctx.ask({ prompt });
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
See [Upgrade to Tasks](/docs/tools/tasks-upgrade) for `task` replacing `execution: "background"`
|
|
251
|
-
and the other changes in this release.
|
|
139
|
+
Only these exports are public. A bare `workflow` or `workflow/*` import in an application module fails the build with an error that names these entries.
|
|
252
140
|
|
|
253
141
|
## Wait for the result
|
|
254
142
|
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
- **Durable wait inside the body:** suspends the workflow while the tool call stays pending.
|
|
260
|
-
- **Cancel:** cancelling the turn cancels the run.
|
|
261
|
-
- **Steering:** a new message aborts the call's `ctx.abortSignal`, and the call settles with what
|
|
262
|
-
the body returns. See [Stop early for a new message](#stop-early-for-a-new-message).
|
|
143
|
+
An `execute` call works like any other tool call. The turn waits for the body to finish and gets its
|
|
144
|
+
output as the tool result. A wait inside the body pauses the workflow while the call stays pending.
|
|
145
|
+
Cancelling the turn cancels the run, and a new message aborts `ctx.abortSignal`; see
|
|
146
|
+
[Stop early for a new message](#stop-early-for-a-new-message).
|
|
263
147
|
|
|
264
148
|
To keep the conversation going while a call works, [define `task` instead](#run-calls-as-tasks-task).
|
|
265
149
|
|
|
266
|
-
`defineWorkflowTool` does not accept an `execution` option. Passing one throws
|
|
267
|
-
`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.`
|
|
268
|
-
|
|
269
150
|
### How suspension works
|
|
270
151
|
|
|
271
|
-
|
|
272
|
-
`
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
functions so replay does not repeat completed effects.
|
|
152
|
+
A workflow pauses, holding no compute, when it awaits an unresolved `ctx.ask`, hook, webhook, or
|
|
153
|
+
`sleep`. When the answer, event, or timer arrives, the workflow replays, reuses recorded step
|
|
154
|
+
results, and continues past the wait. Put side effects in `"use step"` functions so replay doesn't
|
|
155
|
+
repeat them.
|
|
276
156
|
|
|
277
|
-
|
|
157
|
+
In this body, the yield reports progress and the await pauses:
|
|
278
158
|
|
|
279
159
|
```ts
|
|
280
160
|
async *execute(input, ctx) {
|
|
@@ -285,21 +165,15 @@ async *execute(input, ctx) {
|
|
|
285
165
|
}
|
|
286
166
|
```
|
|
287
167
|
|
|
288
|
-
The
|
|
289
|
-
|
|
290
|
-
the body returns.
|
|
291
|
-
|
|
292
|
-
`yield` itself does not wait for approval. An ordinary
|
|
293
|
-
Promise or Node.js timer inside a step also does not create a durable workflow suspension; use
|
|
294
|
-
the workflow operations for waits that must survive a restart.
|
|
168
|
+
The tool call stays pending until the answer arrives and the body returns. An ordinary Promise or
|
|
169
|
+
Node.js timer inside a step doesn't pause the workflow or survive a restart.
|
|
295
170
|
|
|
296
171
|
## Run calls as tasks: `task`
|
|
297
172
|
|
|
298
173
|
Define `task(input, ctx)` in place of `execute` when the conversation should continue while a call
|
|
299
|
-
works
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
doesn't need a task.
|
|
174
|
+
works. Examples are a twenty-minute deploy or research the model may not need right away. Waiting
|
|
175
|
+
alone doesn't need a task, because a question, sleep, or approval in an `execute` call already holds
|
|
176
|
+
no compute.
|
|
303
177
|
|
|
304
178
|
```ts title="agent/tools/deploy.ts"
|
|
305
179
|
import { defineWorkflowTool } from "eve/tools";
|
|
@@ -316,9 +190,8 @@ export default defineWorkflowTool({
|
|
|
316
190
|
});
|
|
317
191
|
```
|
|
318
192
|
|
|
319
|
-
A `task` body
|
|
320
|
-
|
|
321
|
-
steering message never aborts a task's `abortSignal`.
|
|
193
|
+
A `task` body gets the same `WorkflowToolContext` as an `execute` body. Returning finishes the call,
|
|
194
|
+
a throw fails it, and an `async *task` generator can `yield` progress. Steering never aborts a task.
|
|
322
195
|
|
|
323
196
|
Each call is a task with its own id, `<tool>-<6 characters>`:
|
|
324
197
|
|
|
@@ -326,20 +199,18 @@ Each call is a task with its own id, `<tool>-<6 characters>`:
|
|
|
326
199
|
`Started task deploy-4hd8sa. Its result will arrive in a <task_result> message.`, and the model
|
|
327
200
|
continues at once.
|
|
328
201
|
- **Result:** the body's return value or its error arrives later as a `<task_result>` block in a
|
|
329
|
-
`task.result` message
|
|
330
|
-
result, not the receipt.
|
|
202
|
+
`task.result` message. eve adds the message before the model's next step. `toModelOutput` applies
|
|
203
|
+
to the result, not the receipt.
|
|
331
204
|
|
|
332
|
-
The model waits for results with `eve__task_wait` and stops a task with `eve__task_cancel
|
|
333
|
-
end while tasks are working.
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
how held turns look on the stream, steering, events, and limits.
|
|
205
|
+
The model waits for results with `eve__task_wait` and stops a task with `eve__task_cancel`. A turn
|
|
206
|
+
can't end while tasks are working. See [Cancel and clean up](#cancel-and-clean-up-ctxabortsignal)
|
|
207
|
+
for what aborts a task, and [Tasks](/docs/tools/tasks) for what the model sees, held turns, events,
|
|
208
|
+
and limits.
|
|
337
209
|
|
|
338
210
|
## Resumable tasks: `serve`
|
|
339
211
|
|
|
340
212
|
Define `serve(receive, ctx)` when the model should be able to send a running task more input, such
|
|
341
|
-
as a revision request. A `serve` body runs once per task and gets its calls from `receive()
|
|
342
|
-
instead of taking an input:
|
|
213
|
+
as a revision request. A `serve` body runs once per task and gets its calls from `receive()`:
|
|
343
214
|
|
|
344
215
|
```ts title="agent/tools/release-plan.ts"
|
|
345
216
|
import { defineWorkflowTool } from "eve/tools";
|
|
@@ -366,190 +237,80 @@ export default defineWorkflowTool({
|
|
|
366
237
|
```
|
|
367
238
|
|
|
368
239
|
A `serve` tool's calls are tasks, with the receipts and results
|
|
369
|
-
[described above](#run-calls-as-tasks-task)
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
`
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
240
|
+
[described above](#run-calls-as-tasks-task). [Tasks](/docs/tools/tasks) covers waiting, the turn
|
|
241
|
+
rule, who can continue a task, and the task limit.
|
|
242
|
+
|
|
243
|
+
### Receive calls and reply
|
|
244
|
+
|
|
245
|
+
eve adds an optional `taskId` to the tool's model input and explains it in the description. The
|
|
246
|
+
build fails if `inputSchema` declares its own `taskId`. A call without `taskId` starts a new task. Its
|
|
247
|
+
receipt ends with
|
|
248
|
+
`To send it another message, call release-plan again with taskId release-plan-7k2m9q.` A call with
|
|
249
|
+
`taskId` goes to that task. Its receipt starts `Sent to task release-plan-7k2m9q.` The
|
|
250
|
+
`taskId` must name an unfinished task this tool started, or the call fails with `UNKNOWN_TASK`.
|
|
251
|
+
Any caller in the session can send it.
|
|
252
|
+
|
|
253
|
+
- `receive()` resolves with the next call, `{ input, callId, abortSignal }`, with `input` validated
|
|
254
|
+
by `inputSchema`. The first call is the one that started the task. Later calls arrive in order.
|
|
255
|
+
- eve keeps calls that arrive while the body isn't waiting. A second `receive()` while one is
|
|
256
|
+
pending returns the same promise.
|
|
257
|
+
- A call counts as received once its promise resolves, even if it lost a `Promise.race`. The next
|
|
258
|
+
`ctx.reply()` answers it, so keep a raced `receive()` promise until you read the call.
|
|
259
|
+
- `ctx.reply(output)` answers every call received so far. Each call reports its own
|
|
260
|
+
`call.settled`, the model receives the reply once, and the task goes idle until its next call.
|
|
261
|
+
- A reply with no call waiting is dropped, and `ctx.ask` throws while no call is waiting.
|
|
262
|
+
- A reply withdraws the open questions of the calls it answers. It doesn't abort their
|
|
263
|
+
`abortSignal`, so work after the reply keeps running.
|
|
264
|
+
- Returning answers the calls still waiting and ends the task; a throw fails them. `serve` isn't a
|
|
265
|
+
generator, so it can't `yield` progress.
|
|
266
|
+
|
|
267
|
+
### Working, idle, and cancelled tasks
|
|
268
|
+
|
|
269
|
+
- A resumable task is working while one of its calls has no result, and idle otherwise. Only a
|
|
270
|
+
working task holds the turn and counts toward the
|
|
271
|
+
[task limit](/docs/tools/tasks#ownership-and-limits).
|
|
272
|
+
- One stretch of work runs from a call reaching an idle task until a reply or cancel ends its
|
|
273
|
+
calls. Calls in a stretch share one `abortSignal`. The next stretch gets a new one, so a task can
|
|
274
|
+
be cancelled any number of times.
|
|
275
|
+
- `eve__task_cancel`, `session.cancel()`, and a failed turn end the waiting calls as `cancelled`,
|
|
276
|
+
abort the stretch's signal, and make the task idle.
|
|
277
|
+
- To stay available after a cancel, the body must catch the abort and return to `receive()` within
|
|
278
|
+
30 seconds, as the example does. Otherwise the task finishes. A body that ignores the signal keeps
|
|
279
|
+
working, and its reply is dropped.
|
|
280
|
+
- The task finishes when its body returns or throws, or when the session ends. The end of the
|
|
281
|
+
session aborts the current signal and rejects a pending `receive()`.
|
|
282
|
+
|
|
283
|
+
### Calls from several callers
|
|
284
|
+
|
|
285
|
+
A later call can come in a later turn, from a different caller than the one that started the task.
|
|
286
|
+
Once `receive()` resolves with a call, the context describes that call:
|
|
287
|
+
|
|
288
|
+
- `ctx.session.turn` is the call's turn, and `ctx.session.auth` is the auth the session accepted the
|
|
289
|
+
call with. Steps that receive `ctx` see the same values, so `getToken`, `requireAuth`, and
|
|
290
|
+
connections use that call's auth.
|
|
291
|
+
- `ctx.agents` lists the agents the call may open, including dynamic agents selected in its turn.
|
|
292
|
+
- The call's `call.started` and `call.settled` events carry its `callId` and turn. So do the
|
|
293
|
+
questions and sign-ins the body opens while serving it.
|
|
294
|
+
- A session the body opens with `ctx.agent` belongs to that call. Its `session.parent` names the
|
|
295
|
+
call's `callId` and turn, even after later calls. A remote receiver accepts that parent only from
|
|
296
|
+
a trusted forwarder.
|
|
297
|
+
- Each message to that child uses the call's auth. Remote identity follows the
|
|
413
298
|
[forwarding rules](../guides/remote-agents#forwarding-the-caller-identity).
|
|
414
|
-
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
no call left to settle is dropped, and `ctx.ask` throws while no call is waiting for a result.
|
|
418
|
-
A reply also withdraws the questions still pending for the calls it settles, but doesn't abort
|
|
419
|
-
their `abortSignal`, so work the body continues after replying keeps running.
|
|
420
|
-
Returning settles the calls still waiting and ends the task; a throw fails them. `serve` is not
|
|
421
|
-
a generator, so it can't `yield` progress.
|
|
422
|
-
- **Working and idle:** a resumable task is working while one of its calls has no result, and idle
|
|
423
|
-
otherwise. An idle task doesn't hold the turn and doesn't count toward the limit of 32; a call
|
|
424
|
-
that makes it work again does. The `[Tasks]` note lists the 10 most recently used idle tasks
|
|
425
|
-
after the working ones, so the model can find them again.
|
|
426
|
-
- **One `abortSignal` per stretch of work:** a stretch starts when a call reaches an idle task and
|
|
427
|
-
ends when a reply or a cancel settles its calls. Calls that arrive during a stretch share its
|
|
428
|
-
signal, and the next stretch gets a new one, so a task can be cancelled any number of times.
|
|
429
|
-
- **Cancellation:** `eve__task_cancel`, `session.cancel()`, and a failed turn settle the task's waiting
|
|
430
|
-
calls as `cancelled` and abort the stretch's `abortSignal`. The run keeps waiting for more calls,
|
|
431
|
-
so the task becomes idle and stays available. `eve__task_cancel` on an idle task says the task had no
|
|
432
|
-
work to stop. To stay available, a body must catch its stretch's abort and
|
|
433
|
-
return to `receive()`, as the example does; an abort that escapes the body finishes the task. A
|
|
434
|
-
body that ignores the signal keeps working and its reply is dropped, but a body that doesn't
|
|
435
|
-
return to `receive()` within 30 seconds of a cancel ends, and the task finishes.
|
|
436
|
-
- **Finishing:** the task finishes when its body returns or throws, or when the session ends,
|
|
437
|
-
which aborts the current stretch's signal and rejects a pending `receive()`.
|
|
299
|
+
- When trace context is available, a local child's first turn uses the call's tool span as its
|
|
300
|
+
parent. A remote child's first turn starts its own trace, linked to that span with
|
|
301
|
+
`eve.link.type=agent.dispatch`. Later child turns start new traces.
|
|
438
302
|
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
## Authorize inside a step
|
|
446
|
-
|
|
447
|
-
Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there. User-scoped providers
|
|
448
|
-
resolve as whoever launched this workflow tool, even if another person speaks in the session while it waits.
|
|
449
|
-
The provider declaration and the API request both stay inside the step:
|
|
303
|
+
Variables the body keeps between calls, such as `plan`, can hold another caller's output. Key
|
|
304
|
+
per-caller data on these `ctx.session.auth.current` fields together: `authenticator`, `issuer`,
|
|
305
|
+
`principalType`, and `principalId`. A `principalId` is unique only within its authenticator and
|
|
306
|
+
issuer. Anonymous callers, whose `current` is `null` or whose `principalType` is `"anonymous"`,
|
|
307
|
+
share one identity, so don't keep per-person data for them. Any caller in the session can continue
|
|
308
|
+
or cancel the task; see [Tasks](/docs/tools/tasks#ownership-and-limits).
|
|
450
309
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
async function readRepository(ctx: WorkflowStepToolContext, repository: string) {
|
|
456
|
-
"use step";
|
|
457
|
-
const provider = connect("github/my-agent");
|
|
458
|
-
const { token } = await ctx.getToken(provider);
|
|
459
|
-
const response = await fetch(`https://api.github.com/repos/${repository}`, {
|
|
460
|
-
headers: { Authorization: `Bearer ${token}` },
|
|
461
|
-
});
|
|
462
|
-
if (response.status === 401) ctx.requireAuth(provider);
|
|
463
|
-
if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
|
|
464
|
-
return response.json();
|
|
465
|
-
}
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
Connection tools, ordinary tools, and workflow steps use the same
|
|
469
|
-
authorization machinery for requester identity, token caching, callback completion, and rejection
|
|
470
|
-
after sign-in. The execution runtime owns the wait: an agent returns to its model after authorization,
|
|
471
|
-
while a workflow retries the interrupted step and continues the authored body.
|
|
472
|
-
|
|
473
|
-
The workflow body calls `await readRepository(ctx, repository)`.
|
|
474
|
-
|
|
475
|
-
<Callout type="warning" title="Keep tokens out of step results">
|
|
476
|
-
Step results enter the workflow's durable history, so do not return the token from the helper.
|
|
477
|
-
eve's token cache stays inside the step. The step input is recorded too and, after sign-in,
|
|
478
|
-
carries the provider's callback parameters, such as a one-time authorization code. This matches
|
|
479
|
-
how agent turns record callbacks. Bearer tokens are never written.
|
|
480
|
-
</Callout>
|
|
481
|
-
|
|
482
|
-
When sign-in is required, the step attempt ends and the workflow waits on its own callback hook,
|
|
483
|
-
without holding compute. The channel renders the sign-in challenge. After the callback, eve retries
|
|
484
|
-
**the whole interrupted step**, resolves the token, and continues. Previously completed steps are
|
|
485
|
-
not rerun. Resolve auth before other side effects in that step, and make operations before
|
|
486
|
-
`requireAuth` safe to retry. A token rejected immediately after sign-in fails instead of prompting
|
|
487
|
-
again. Provider declarations can be shared imports, but context must be passed directly, not nested
|
|
488
|
-
inside another argument or captured in a closure.
|
|
489
|
-
|
|
490
|
-
After a successful callback exchange, eve records a completion marker before returning to authored
|
|
491
|
-
code. If that code later fails and the step retries, eve reads the token from the provider instead
|
|
492
|
-
of exchanging the same callback again. The provider must persist the grant or token; the marker
|
|
493
|
-
itself contains no credentials.
|
|
494
|
-
|
|
495
|
-
Cancelling an authorization wait withdraws its callback. Cancellation uses the existing turn
|
|
496
|
-
cancellation path rather than a separate authorization completion event.
|
|
497
|
-
|
|
498
|
-
## Use the session sandbox in a step
|
|
499
|
-
|
|
500
|
-
Pass `ctx` directly to a step helper and call `ctx.getSandbox()` there. The step opens the
|
|
501
|
-
[sandbox](/docs/sandbox) of the session that called the tool, the same sandbox that session's
|
|
502
|
-
turns use. When the session shares its parent's sandbox, as a copy started by the built-in `agent`
|
|
503
|
-
tool does, the step opens that shared sandbox. The step sees files the session wrote, and the
|
|
504
|
-
session's later tool calls see files the step writes:
|
|
505
|
-
|
|
506
|
-
```ts title="agent/tools/analyze.ts"
|
|
507
|
-
import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
|
|
508
|
-
import { z } from "zod";
|
|
509
|
-
|
|
510
|
-
export default defineWorkflowTool({
|
|
511
|
-
description: "Prepare the input file for an analysis run.",
|
|
512
|
-
inputSchema: z.object({ value: z.string() }),
|
|
513
|
-
async task(input, ctx) {
|
|
514
|
-
"use workflow";
|
|
515
|
-
await prepareInput(ctx, input);
|
|
516
|
-
return { path: "/workspace/input.json" };
|
|
517
|
-
},
|
|
518
|
-
});
|
|
519
|
-
|
|
520
|
-
async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string }) {
|
|
521
|
-
"use step";
|
|
522
|
-
const sandbox = await ctx.getSandbox();
|
|
523
|
-
await sandbox.writeTextFile({ path: "/workspace/input.json", content: JSON.stringify(input) });
|
|
524
|
-
}
|
|
525
|
-
```
|
|
526
|
-
|
|
527
|
-
- The workflow body cannot open the sandbox, because it replays. `ctx.getSandbox()` in the body
|
|
528
|
-
throws and tells you to pass `ctx` to a step helper.
|
|
529
|
-
- The step opens the sandbox directly, with any sandbox provider. If the session recorded its
|
|
530
|
-
sandbox before it called the tool, the step resumes it. Otherwise, or if that sandbox is gone by
|
|
531
|
-
the time the step runs, the step opens it the way the session's first turn would: it runs your
|
|
532
|
-
`defineSandbox()` definition, and the provider finds or creates the sandbox by the session's id. The session's later turns open the same sandbox. Your
|
|
533
|
-
definition can run once for each caller that opens the sandbox before the session records it,
|
|
534
|
-
so make its initialization safe to repeat.
|
|
535
|
-
- The step does not own the sandbox. When the step ends, even by throwing, eve lets go of the
|
|
536
|
-
step's handle and leaves the sandbox running for the session. eve never stops or deletes the
|
|
537
|
-
sandbox for a step, and `sandbox.stop()` and `sandbox.delete()` in a step fail without a retry,
|
|
538
|
-
because the session's turns may be using the sandbox.
|
|
539
|
-
- The session removes the sandbox when the session ends, even when only a step opened it. A step
|
|
540
|
-
that is still running when the session ends can open the sandbox again after that cleanup, and
|
|
541
|
-
nothing removes the new one.
|
|
542
|
-
- When the eve server shuts down, it stops the sandboxes its sessions opened, but not one that
|
|
543
|
-
only a step opened. With Docker, that container keeps running until the session ends or you
|
|
544
|
-
stop it.
|
|
545
|
-
- A step can use the sandbox while the session's turns use it too, as subagents that share a
|
|
546
|
-
sandbox do. Give each one its own files to write.
|
|
547
|
-
- Steps run at least once and retry after a failure, so make sandbox writes safe to repeat. Write
|
|
548
|
-
whole files instead of appending to them, or check for earlier output first.
|
|
549
|
-
- When the session shares its parent's sandbox, the step opens it by the parent's session id with
|
|
550
|
-
the parent's sandbox definition, and the parent removes it when the parent ends.
|
|
551
|
-
- A step runs wherever the workflow runs. A sandbox that lives on one machine, such as just-bash
|
|
552
|
-
on the local disk, is reachable from a step only on that machine, as in local development.
|
|
310
|
+
Every [agent tool](/docs/subagents), including the built-in `agent` tool and remote agents, is a
|
|
311
|
+
`serve` tool. Each agent task holds one session with the agent and replies with the final response
|
|
312
|
+
of each agent turn. Unlike other `serve` tasks, cancelling an agent task ends it, so start a new
|
|
313
|
+
task to delegate again.
|
|
553
314
|
|
|
554
315
|
## Ask a human: `ctx.ask`
|
|
555
316
|
|
|
@@ -569,24 +330,21 @@ const answer = await ctx.ask(
|
|
|
569
330
|
// | { status: "unavailable" }
|
|
570
331
|
```
|
|
571
332
|
|
|
572
|
-
`ctx.ask` opens
|
|
573
|
-
|
|
574
|
-
|
|
333
|
+
`ctx.ask` opens a question on the session, reported as `interaction.opened`, and channels show it
|
|
334
|
+
like a tool approval. Awaiting the answer pauses the run. The provided `ask_question` tool is built
|
|
335
|
+
on `ctx.ask`.
|
|
575
336
|
|
|
576
|
-
|
|
337
|
+
| `status` | Meaning |
|
|
338
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
339
|
+
| `answered` | The person picked an option (`optionId`) or typed a reply (`text`). |
|
|
340
|
+
| `cancelled` | The question was withdrawn before anyone answered, because `signal` or the call's `abortSignal` aborted or a `serve` body replied to the call. The stream reports `interaction.settled` as `withdrawn`, so clients stop offering it. |
|
|
341
|
+
| `unavailable` | The session cannot ask for input, such as a scheduled run. `ctx.ask` returns this immediately. |
|
|
577
342
|
|
|
578
|
-
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
session settles the interaction `withdrawn`, so clients stop offering the question.
|
|
582
|
-
- `unavailable`: the session cannot request input, such as a scheduled run. `ctx.ask` returns this
|
|
583
|
-
immediately instead of waiting for an answer no one can give.
|
|
343
|
+
A plain follow-up message answers the question when it is the only one open. The message must match
|
|
344
|
+
an option, or the question must allow free text. Answer a question from a subagent with a structured
|
|
345
|
+
response.
|
|
584
346
|
|
|
585
|
-
|
|
586
|
-
matches an option or the request allows free text. Answer a question from a subagent with a
|
|
587
|
-
structured response.
|
|
588
|
-
|
|
589
|
-
`ctx.ask` composes with the SDK's own constructs; race it against a deadline:
|
|
347
|
+
Race `ctx.ask` against `sleep` for a deadline:
|
|
590
348
|
|
|
591
349
|
```ts
|
|
592
350
|
const pending = ctx.ask({ prompt: `Deploy ${service}?`, options: APPROVE_OR_CANCEL });
|
|
@@ -594,24 +352,23 @@ const answer = await Promise.race([pending, sleep("4h")]);
|
|
|
594
352
|
if (answer === undefined) return { deployed: false, reason: "timed out" };
|
|
595
353
|
```
|
|
596
354
|
|
|
597
|
-
- The
|
|
598
|
-
or the run ends.
|
|
599
|
-
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
person's answer reached the session first, the ask resolves as `answered` even though the signal
|
|
611
|
-
aborted, and the channel shows it answered. Branch on `status`, not on the signal.
|
|
355
|
+
- The question belongs to the run, not the turn. It stays open until someone answers it, it is
|
|
356
|
+
withdrawn, or the run ends by returning, throwing, or cancellation.
|
|
357
|
+
- Each question is answered once, so ask again for the next answer. Several questions can be open
|
|
358
|
+
at once.
|
|
359
|
+
- A response carries only the option `id`, so choose ids that read well on their own, such as
|
|
360
|
+
`approve`. If a person answers after the question ended, for example from an old Slack menu, the
|
|
361
|
+
agent receives the `id` as a new message.
|
|
362
|
+
- A response never steers. A new message that answers no open question follows the session's
|
|
363
|
+
`turnPolicy`. Steering withdraws the questions of the `execute` calls the turn waits on, such as
|
|
364
|
+
`ask_question`'s, but not a task's. See [Stop early for a new message](#stop-early-for-a-new-message).
|
|
365
|
+
- An aborted `signal` asks the session to withdraw the question. If a person's answer reached the
|
|
366
|
+
session first, the ask resolves as `answered` and the channel shows it answered. Branch on
|
|
367
|
+
`status`, not on the signal.
|
|
612
368
|
|
|
613
369
|
Compare the [`approval`](/docs/human-in-the-loop) policy, which gates the call before `execute` runs
|
|
614
|
-
and can only show the model's input.
|
|
370
|
+
and can only show the model's input. Use both together: `approval` before the run, `ctx.ask` inside
|
|
371
|
+
it.
|
|
615
372
|
|
|
616
373
|
## Delegate work: `ctx.agent`
|
|
617
374
|
|
|
@@ -630,8 +387,8 @@ const response = await reviewer.send("Review the deployment plan for security ri
|
|
|
630
387
|
const { data, reply, status } = await response.result();
|
|
631
388
|
```
|
|
632
389
|
|
|
633
|
-
Set `model`
|
|
634
|
-
|
|
390
|
+
Set `model` to run a local child on a different AI Gateway model. Every message sent through the
|
|
391
|
+
returned session uses it:
|
|
635
392
|
|
|
636
393
|
```ts
|
|
637
394
|
const reviewer = ctx.agent("agent", {
|
|
@@ -657,24 +414,26 @@ const reviewer = ctx.agent("agent", {
|
|
|
657
414
|
});
|
|
658
415
|
```
|
|
659
416
|
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
417
|
+
Omit `modelContextWindowTokens` to read the context window from the AI Gateway model catalog
|
|
418
|
+
recorded at build time. Set it for a model the catalog doesn't list; otherwise the first `send`
|
|
419
|
+
rejects.
|
|
663
420
|
|
|
664
|
-
The selection must contain an AI Gateway model id
|
|
665
|
-
|
|
421
|
+
The selection must contain an AI Gateway model id, because a live AI SDK `LanguageModel` can't be
|
|
422
|
+
saved across waits. A remote agent rejects `model`, because its deployment owns its model
|
|
666
423
|
configuration.
|
|
667
424
|
|
|
668
|
-
The name is an available agent target
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
425
|
+
The name is an available agent target:
|
|
426
|
+
|
|
427
|
+
- On the root agent, `"agent"` starts a copy of the root agent. Delegated root copies and declared
|
|
428
|
+
subagents can't open that copy.
|
|
429
|
+
- A declared subagent uses its path-derived name, and stays callable when hidden with `tool: false`
|
|
430
|
+
or `disableTool()`.
|
|
431
|
+
- The name `agent` is reserved, so a declared subagent can't use it.
|
|
432
|
+
- An unavailable name rejects the first `send`.
|
|
673
433
|
|
|
674
|
-
`send(message, options?)` accepts text or `MessageContent<string | URL>`: up to 64 text and
|
|
675
|
-
|
|
676
|
-
and `data:` URLs
|
|
677
|
-
inputs. Upload a local file first, then send its URL:
|
|
434
|
+
`send(message, options?)` accepts text or `MessageContent<string | URL>`: up to 64 text and file
|
|
435
|
+
parts. File `data` must be an HTTP(S) URL, as a string or `URL` object. eve rejects inline bytes,
|
|
436
|
+
base64, and `data:` URLs before sending, so upload a local file first and send its URL:
|
|
678
437
|
|
|
679
438
|
```ts
|
|
680
439
|
await reviewer.send([
|
|
@@ -683,46 +442,50 @@ await reviewer.send([
|
|
|
683
442
|
]);
|
|
684
443
|
```
|
|
685
444
|
|
|
686
|
-
The options are:
|
|
687
|
-
|
|
688
445
|
| Option | Description |
|
|
689
446
|
| -------------- | -------------------------------------------------------------------------------------------------------- |
|
|
690
447
|
| `outputSchema` | Structured output for the turn, as a Standard JSON Schema such as a Zod schema, or a JSON Schema object. |
|
|
691
448
|
| `signal` | Aborting it cancels the turn the message started or joined. The turn still reports, as cancelled. |
|
|
692
449
|
|
|
693
|
-
A message sent while the
|
|
694
|
-
that turn's result. If the turn ends before the agent reads the message, the message starts the
|
|
695
|
-
turn
|
|
696
|
-
|
|
697
|
-
|
|
450
|
+
A message sent while the child's turn is running joins that turn, and its response resolves with
|
|
451
|
+
that turn's result. If the turn ends before the agent reads the message, the message starts the
|
|
452
|
+
next turn. Its response, and those of earlier messages still waiting, resolve with that turn's
|
|
453
|
+
result. A message sent while the session is idle starts the next turn. The session keeps its
|
|
454
|
+
conversation between turns.
|
|
455
|
+
|
|
456
|
+
`result()` returns:
|
|
698
457
|
|
|
699
458
|
| Field | Description |
|
|
700
459
|
| -------------- | --------------------------------------------------------------------------------------------------------- |
|
|
701
460
|
| `data` | The structured value, when the turn requested `outputSchema`. |
|
|
702
461
|
| `reply` | The agent's final reply text, when available. |
|
|
703
462
|
| `status` | `"completed"`, `"failed"`, or `"cancelled"`. Completion does not by itself mean the session ended. |
|
|
704
|
-
| `sessionEnded` | Whether the session ended
|
|
463
|
+
| `sessionEnded` | Whether the session ended with this turn. |
|
|
705
464
|
| `error` | `{ message }` with the reason the turn failed. Required when `status` is `"failed"` and absent otherwise. |
|
|
706
465
|
|
|
707
|
-
|
|
708
|
-
The model
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
466
|
+
Each `ctx.agent(name, options?)` call returns a new session that only this workflow run can send to.
|
|
467
|
+
The model sees only what the tool returns. The session ends when the run finishes, which cancels any
|
|
468
|
+
turn still running.
|
|
469
|
+
|
|
470
|
+
- **Local child:** runs with the caller's auth.
|
|
471
|
+
- **Remote child:** its identity comes from the outbound request, not the caller's session. To
|
|
472
|
+
forward the caller's identity, set `forwardPrincipal: true` on the remote agent and configure the
|
|
473
|
+
receiver's `trustedForwarders`. See
|
|
474
|
+
[Forwarding the caller identity](../guides/remote-agents#forwarding-the-caller-identity).
|
|
475
|
+
- **Questions and sign-ins:** a person answers the child's questions and sign-ins at the root
|
|
476
|
+
session, as for any subagent.
|
|
715
477
|
|
|
716
|
-
The parent stream announces each session with `child.opened
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
[`session.agent(opened).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the
|
|
478
|
+
The parent stream announces each session with `child.opened`. The event carries the agent `name`,
|
|
479
|
+
the child's `sessionId`, its `stream` path, and its `owner`. `owner` is the task whose run opened
|
|
480
|
+
the session, or the tool call when the call doesn't run as a task. Pass the event to
|
|
481
|
+
[`session.agent(opened).stream()`](/docs/guides/client/streaming#follow-a-subagent) to follow the
|
|
482
|
+
child.
|
|
720
483
|
|
|
721
484
|
### Route to a hidden subagent with Jev
|
|
722
485
|
|
|
723
|
-
Use an authored workflow tool when the parent model should decide to delegate, but [Jev](https://vercel.com/i/what-is-jev) should choose the specialist. Set `tool: false` on each specialist so the parent model sees only the routing tool.
|
|
486
|
+
Use an authored workflow tool when the parent model should decide to delegate, but [Jev](https://vercel.com/i/what-is-jev) should choose the specialist. Set `tool: false` on each specialist so the parent model sees only the routing tool. `ctx.agents` and `ctx.agent()` still reach the specialists.
|
|
724
487
|
|
|
725
|
-
If the router may select the root-copy `agent`,
|
|
488
|
+
If the router may select the root-copy `agent`, give the root a `description` that says which work should stay with a copy of the root. Without one, `ctx.agents.agent.description` is an empty string, which `agentRouter()` skips.
|
|
726
489
|
|
|
727
490
|
```ts title="agent/agent.ts"
|
|
728
491
|
import { defineAgent } from "eve";
|
|
@@ -753,7 +516,7 @@ export default defineAgent({
|
|
|
753
516
|
});
|
|
754
517
|
```
|
|
755
518
|
|
|
756
|
-
Define the model-visible router under `agent/tools/`. Build the Jev criteria from the subagents'
|
|
519
|
+
Define the model-visible router under `agent/tools/`. Build the Jev criteria from the subagents' descriptions, then pass its typed choice to `ctx.agent()`:
|
|
757
520
|
|
|
758
521
|
```ts title="agent/tools/agent-router.ts"
|
|
759
522
|
import { decide } from "eve/ai";
|
|
@@ -805,9 +568,9 @@ export default defineWorkflowTool({
|
|
|
805
568
|
});
|
|
806
569
|
```
|
|
807
570
|
|
|
808
|
-
The decision runs in a step so
|
|
571
|
+
The decision runs in a step, so replay reuses it instead of repeating the routing request. The parent model sees only `agent-router`, and the selected subagent's reply becomes its tool result.
|
|
809
572
|
|
|
810
|
-
`ctx.agents`
|
|
573
|
+
`ctx.agents` holds agent metadata as it was when the session accepted the call, and replay doesn't change it. In a `serve` task, it follows the call being served. It includes agents hidden with `tool: false` or `disableTool()`, but no model definitions, credentials, or callbacks. In a top-level root workflow, `ctx.agents.agent` always exists as the root-copy target. A delegated root copy omits `agent`, so `agentRouter()` can't select another root copy. `ctx.agent()` still checks each target's availability.
|
|
811
574
|
|
|
812
575
|
#### Route across every agent target
|
|
813
576
|
|
|
@@ -819,13 +582,68 @@ import { agentRouter } from "eve/tools/agent_router";
|
|
|
819
582
|
export default agentRouter();
|
|
820
583
|
```
|
|
821
584
|
|
|
822
|
-
Its input is `{ message: string }`. `agentRouter()`
|
|
823
|
-
runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
|
|
585
|
+
Its input is `{ message: string }`. `agentRouter()` considers only targets with a non-empty description. With two or more, Jev picks one from the message and descriptions; a sole target gets the message directly. The router sends the message to a new session with that agent. Each call runs as a [task](#run-calls-as-tasks-task), so the reply reaches the model as the task's result. In a top-level root session, the candidates include the root-copy `agent`; delegated root copies and declared subagent contexts include only their declared targets.
|
|
824
586
|
|
|
825
587
|
When an authored tool accepts a JSON Schema supplied by the model, represent that input with a permissive object such as `z.looseObject({})`. Avoid `z.record(z.string(), z.json())`: its generated JSON Schema uses `propertyNames`, which OpenAI does not support. Validate the supplied value at the point where your tool consumes it.
|
|
826
588
|
|
|
827
589
|
This pattern controls specialist selection, not whether the parent model delegates at all. Route before the parent model runs if every incoming request must go through Jev.
|
|
828
590
|
|
|
591
|
+
## Add a runtime-generated workflow tool
|
|
592
|
+
|
|
593
|
+
Export the provided `workflow` factory from `agent/tools/workflow.ts` when the model should write the
|
|
594
|
+
JavaScript program at runtime:
|
|
595
|
+
|
|
596
|
+
```ts title="agent/tools/workflow.ts"
|
|
597
|
+
import { workflow } from "eve/tools/workflow";
|
|
598
|
+
|
|
599
|
+
export default workflow({ maxSubagents: 20 });
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
The model supplies an async function body through the tool's `js` input. Each call runs as a
|
|
603
|
+
[task](#run-calls-as-tasks-task), so the program's return value reaches the model in a
|
|
604
|
+
`task.result` message.
|
|
605
|
+
|
|
606
|
+
The program can only call `ctx.agent(name, { message, outputSchema? })`. It sends the message to a
|
|
607
|
+
new session with that agent, and resolves to the reply or, when `outputSchema` is set, to the
|
|
608
|
+
structured value. The program can call subagents hidden with `tool: false` or a same-named
|
|
609
|
+
`disableTool()` file, so list their path-derived names in the tool description or agent
|
|
610
|
+
instructions:
|
|
611
|
+
|
|
612
|
+
```js
|
|
613
|
+
const [triage, review] = await Promise.all([
|
|
614
|
+
ctx.agent("ticket-triage", { message: JSON.stringify(tickets) }),
|
|
615
|
+
ctx.agent("ticket-review", { message: JSON.stringify(tickets) }),
|
|
616
|
+
]);
|
|
617
|
+
return { triage, review };
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
Omit `maxSubagents` to allow `100` agent calls; set an integer from `1` through `128`. The program
|
|
621
|
+
can't use the workflow context, session state, credentials, imports, or ordinary tools. Each
|
|
622
|
+
`ctx.agent` call starts a new child session, so a program can't continue a child from an earlier
|
|
623
|
+
call. Agent authorization, questions, approvals, and cancellation work as they do for sessions an
|
|
624
|
+
authored workflow tool opens with `ctx.agent`.
|
|
625
|
+
|
|
626
|
+
The program continues after every pending call in the current batch finishes, so `Promise.all`
|
|
627
|
+
supports fan-out followed by fan-in. A `ctx.agent` call still pending when the program returns
|
|
628
|
+
fails the workflow, such as one never awaited or one that loses a `Promise.race` or `Promise.any`.
|
|
629
|
+
|
|
630
|
+
A failed child turn, an invalid call, or a call over the `maxSubagents` budget throws a catchable
|
|
631
|
+
`WorkflowProgramAgentError` at that `ctx.agent` call. The error message names the cause.
|
|
632
|
+
|
|
633
|
+
The return value and each `ctx.agent` input pass through `JSON.stringify`, so a `Date` becomes a
|
|
634
|
+
string, and functions and `undefined` members drop. A return value that converts to nothing, such
|
|
635
|
+
as `undefined`, becomes `null`.
|
|
636
|
+
|
|
637
|
+
| Limit | Value |
|
|
638
|
+
| ----------------------------------------- | ---------- |
|
|
639
|
+
| Return value or `ctx.agent` input as JSON | 1 MiB |
|
|
640
|
+
| Child reply as JSON | 4 MiB |
|
|
641
|
+
| Program source | 256 KiB |
|
|
642
|
+
| JavaScript time per start or resume | 30 seconds |
|
|
643
|
+
| Total time per start or resume | 5 minutes |
|
|
644
|
+
|
|
645
|
+
Time spent waiting for child agents does not count toward either time limit.
|
|
646
|
+
|
|
829
647
|
## Start channel sessions: `ctx.to`
|
|
830
648
|
|
|
831
649
|
A workflow tool reaches the agent's channels with [`ctx.to(channel, target)`](/docs/tools#start-channel-sessions-ctxto), as an ordinary tool does. Call it in a `"use step"` helper that receives `ctx`, like `ctx.getSandbox()`; the workflow body throws when it calls it:
|
|
@@ -864,27 +682,24 @@ async function openIncident(ctx: WorkflowStepToolContext, channelId: string, sum
|
|
|
864
682
|
}
|
|
865
683
|
```
|
|
866
684
|
|
|
867
|
-
A step
|
|
685
|
+
A failed step retries, so pass an `idempotencyKey` that the retry repeats. Include `ctx.session.id`, because the target session dedupes keys from every sender. Add a label for each send, because `ctx.callId` is the same for every step of the call. Create the channel in its own step, so a retried send step reuses the saved `channelId` instead of creating another channel.
|
|
868
686
|
|
|
869
687
|
`ctx.channel` holds the `kind`, `continuationToken`, and `metadata` of the channel serving the calling session, in the workflow body and in steps, as in [ordinary tools](/docs/tools#the-ctx-parameter).
|
|
870
688
|
|
|
871
689
|
## Report progress: `yield`
|
|
872
690
|
|
|
873
|
-
A workflow body
|
|
874
|
-
|
|
691
|
+
A workflow body can be an async generator whose yields report progress. A yield doesn't pause the
|
|
692
|
+
body; await a workflow operation to pause.
|
|
875
693
|
|
|
876
694
|
| Operation | Behavior |
|
|
877
695
|
| --------------- | ----------------------------------------------------------------- |
|
|
878
696
|
| `yield value` | Emits a `call.progress` snapshot for the pending tool call. |
|
|
879
|
-
| `return value` |
|
|
697
|
+
| `return value` | Ends the tool call with its output. |
|
|
880
698
|
| No return value | Uses the last yield as output, or `null` if there were no yields. |
|
|
881
699
|
|
|
882
|
-
An explicit `return null` also falls back to the last yield
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
intermediate tool results. A snapshot used as the final output does enter history as the tool result.
|
|
886
|
-
|
|
887
|
-
This workflow reports progress, then suspends until its timer expires:
|
|
700
|
+
An explicit `return null` also falls back to the last yield, so return an object when progress
|
|
701
|
+
snapshots and the final result have different shapes. Each snapshot replaces the previous one and
|
|
702
|
+
stays out of the model's history, unless it becomes the final output.
|
|
888
703
|
|
|
889
704
|
```ts title="agent/tools/remind_with_progress.ts"
|
|
890
705
|
import { defineWorkflowTool } from "eve/tools";
|
|
@@ -903,16 +718,15 @@ export default defineWorkflowTool({
|
|
|
903
718
|
});
|
|
904
719
|
```
|
|
905
720
|
|
|
906
|
-
|
|
907
|
-
[yield and return](/docs/tools#yield-and-return) for the final-output rules.
|
|
721
|
+
See [yield and return](/docs/tools#yield-and-return) for the final-output rules.
|
|
908
722
|
|
|
909
723
|
## Cancel and clean up: `ctx.abortSignal`
|
|
910
724
|
|
|
911
|
-
`ctx.abortSignal` aborts when the call is cancelled
|
|
912
|
-
`eve__task_cancel`, a failed turn, or the end of the session.
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
725
|
+
`ctx.abortSignal` aborts when the call is cancelled by `session.cancel()`. For a task, it also aborts
|
|
726
|
+
on `eve__task_cancel`, a failed turn, or the end of the session. For an `execute` call, a steering
|
|
727
|
+
message aborts it too; see [Stop early for a new message](#stop-early-for-a-new-message). The signal
|
|
728
|
+
survives replay, and a step that receives it sees the abort. Pass it into the steps that should
|
|
729
|
+
stop, and clean up in `try/finally`:
|
|
916
730
|
|
|
917
731
|
```ts
|
|
918
732
|
async execute({ projectId }, ctx) {
|
|
@@ -926,34 +740,33 @@ async execute({ projectId }, ctx) {
|
|
|
926
740
|
}
|
|
927
741
|
```
|
|
928
742
|
|
|
929
|
-
After a cancel
|
|
930
|
-
|
|
931
|
-
the
|
|
932
|
-
clean up first.
|
|
743
|
+
After a cancel, the run waits up to 30 seconds for the body to stop, then ends as cancelled whether
|
|
744
|
+
or not it did. A body paused on a hook or a `sleep` doesn't see the signal. eve abandons it when
|
|
745
|
+
the 30 seconds end, so clean up in steps that received the signal.
|
|
933
746
|
|
|
934
|
-
The caller waits up to 35 seconds for a
|
|
935
|
-
|
|
747
|
+
The caller waits up to 35 seconds for a cancelled run to report its outcome, then forces the run to
|
|
748
|
+
stop.
|
|
936
749
|
|
|
937
750
|
## Stop early for a new message
|
|
938
751
|
|
|
939
|
-
A steering message
|
|
940
|
-
|
|
941
|
-
|
|
752
|
+
A steering message is one sent with `turnPolicy: "steer"` (the default) that answers no open
|
|
753
|
+
question. It aborts the `ctx.abortSignal` of each `execute` call the turn waits on. A message that
|
|
754
|
+
answers a question never stops a call, and steering never touches a
|
|
942
755
|
[task](#run-calls-as-tasks-task).
|
|
943
756
|
|
|
944
|
-
Steering does not cancel the call or end the turn. The call
|
|
945
|
-
|
|
757
|
+
Steering does not cancel the call or end the turn. The call ends with what the body returns, and the
|
|
758
|
+
model reads the new message after the step's workflow tool calls finish:
|
|
946
759
|
|
|
947
|
-
- **Questions:**
|
|
760
|
+
- **Questions:** an open `ctx.ask` question is withdrawn and resolves as `cancelled`, unless a
|
|
948
761
|
person's answer reached the session first.
|
|
949
762
|
- **Rejections:** a body that rejects after the abort, such as one whose step received the signal,
|
|
950
|
-
|
|
951
|
-
- **
|
|
952
|
-
|
|
763
|
+
ends as `{ interrupted: true }` instead of failing.
|
|
764
|
+
- **Paused bodies:** a body paused on a hook or a `sleep` doesn't see the signal, and it keeps the
|
|
765
|
+
turn waiting until it finishes.
|
|
953
766
|
|
|
954
|
-
The body doesn't need to tell a steering message from a cancel:
|
|
955
|
-
|
|
956
|
-
|
|
767
|
+
The body doesn't need to tell a steering message from a cancel: stop and return what you have.
|
|
768
|
+
After a cancel, eve discards the result. The provided `sleep` tool races its timer against the
|
|
769
|
+
signal:
|
|
957
770
|
|
|
958
771
|
```ts
|
|
959
772
|
import { sleep } from "eve/workflow";
|
|
@@ -972,6 +785,101 @@ async execute(input, ctx) {
|
|
|
972
785
|
To keep a question or long work going while the conversation continues, define
|
|
973
786
|
[`task`](#run-calls-as-tasks-task) instead of `execute`.
|
|
974
787
|
|
|
788
|
+
## Authorize inside a step
|
|
789
|
+
|
|
790
|
+
Pass `ctx` directly to a step helper and call `ctx.getToken(provider)` there, with the provider
|
|
791
|
+
declaration and the API request inside the step. User-scoped providers resolve as the person whose
|
|
792
|
+
call started the workflow tool, even if another person speaks in the session while it waits:
|
|
793
|
+
|
|
794
|
+
```ts
|
|
795
|
+
import { connect } from "@vercel/connect/eve";
|
|
796
|
+
import type { WorkflowStepToolContext } from "eve/tools";
|
|
797
|
+
|
|
798
|
+
async function readRepository(ctx: WorkflowStepToolContext, repository: string) {
|
|
799
|
+
"use step";
|
|
800
|
+
const provider = connect("github/my-agent");
|
|
801
|
+
const { token } = await ctx.getToken(provider);
|
|
802
|
+
const response = await fetch(`https://api.github.com/repos/${repository}`, {
|
|
803
|
+
headers: { Authorization: `Bearer ${token}` },
|
|
804
|
+
});
|
|
805
|
+
if (response.status === 401) ctx.requireAuth(provider);
|
|
806
|
+
if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
|
|
807
|
+
return response.json();
|
|
808
|
+
}
|
|
809
|
+
```
|
|
810
|
+
|
|
811
|
+
The workflow body calls `await readRepository(ctx, repository)`.
|
|
812
|
+
|
|
813
|
+
<Callout type="warning" title="Keep tokens out of step results">
|
|
814
|
+
eve records step results in the workflow's history, so do not return the token from the helper.
|
|
815
|
+
The step input is recorded too and, after sign-in, carries the provider's callback parameters,
|
|
816
|
+
such as a one-time authorization code. Bearer tokens are never written.
|
|
817
|
+
</Callout>
|
|
818
|
+
|
|
819
|
+
When sign-in is required, the step attempt ends and the channel shows the sign-in prompt. The
|
|
820
|
+
workflow waits for the callback without holding compute. After the callback, eve retries **the whole
|
|
821
|
+
interrupted step**, resolves the token, and continues. Completed steps don't run again.
|
|
822
|
+
|
|
823
|
+
- Resolve auth before other side effects in that step, and make operations before `requireAuth`
|
|
824
|
+
safe to retry.
|
|
825
|
+
- A token rejected immediately after sign-in fails instead of prompting again.
|
|
826
|
+
- Provider declarations can be shared imports. Pass `ctx` directly, not nested inside another
|
|
827
|
+
argument or captured in a closure.
|
|
828
|
+
- If the step fails and retries after a successful sign-in, eve reads the token from the provider
|
|
829
|
+
instead of reusing the callback. The provider must therefore persist the grant or token.
|
|
830
|
+
- Cancelling an authorization wait withdraws its callback.
|
|
831
|
+
|
|
832
|
+
## Use the session sandbox in a step
|
|
833
|
+
|
|
834
|
+
Pass `ctx` directly to a step helper and call `ctx.getSandbox()` there. The step opens the
|
|
835
|
+
[sandbox](/docs/sandbox) that the calling session's turns use. That includes a sandbox shared with
|
|
836
|
+
a parent session, as in a copy started by the built-in `agent` tool. The step and the session see
|
|
837
|
+
each other's files:
|
|
838
|
+
|
|
839
|
+
```ts title="agent/tools/analyze.ts"
|
|
840
|
+
import { defineWorkflowTool, type WorkflowStepToolContext } from "eve/tools";
|
|
841
|
+
import { z } from "zod";
|
|
842
|
+
|
|
843
|
+
export default defineWorkflowTool({
|
|
844
|
+
description: "Prepare the input file for an analysis run.",
|
|
845
|
+
inputSchema: z.object({ value: z.string() }),
|
|
846
|
+
async task(input, ctx) {
|
|
847
|
+
"use workflow";
|
|
848
|
+
await prepareInput(ctx, input);
|
|
849
|
+
return { path: "/workspace/input.json" };
|
|
850
|
+
},
|
|
851
|
+
});
|
|
852
|
+
|
|
853
|
+
async function prepareInput(ctx: WorkflowStepToolContext, input: { value: string }) {
|
|
854
|
+
"use step";
|
|
855
|
+
const sandbox = await ctx.getSandbox();
|
|
856
|
+
await sandbox.writeTextFile({ path: "/workspace/input.json", content: JSON.stringify(input) });
|
|
857
|
+
}
|
|
858
|
+
```
|
|
859
|
+
|
|
860
|
+
- The workflow body can't open the sandbox, because it replays. `ctx.getSandbox()` in the body
|
|
861
|
+
throws and tells you to pass `ctx` to a step helper.
|
|
862
|
+
- The step works with any sandbox provider. If the session recorded its sandbox before it called
|
|
863
|
+
the tool, the step resumes it. Otherwise, or if that sandbox is gone, the step runs your
|
|
864
|
+
`defineSandbox()` definition as the session's first turn would. Later turns open the same sandbox.
|
|
865
|
+
- Your definition can run once for each caller that opens the sandbox before the session records
|
|
866
|
+
it, so make its setup safe to repeat.
|
|
867
|
+
- The sandbox belongs to the session, not the step. When the step ends, even by throwing, the
|
|
868
|
+
sandbox keeps running. `sandbox.stop()` and `sandbox.delete()` in a step fail without a retry,
|
|
869
|
+
because the session's turns may be using the sandbox.
|
|
870
|
+
- The session removes the sandbox when it ends, even when only a step opened it. A step still
|
|
871
|
+
running at that point can open the sandbox again, and nothing removes the new one.
|
|
872
|
+
- When the eve server shuts down, it stops the sandboxes its sessions opened, but not one that only
|
|
873
|
+
a step opened. With Docker, that container keeps running until the session ends or you stop it.
|
|
874
|
+
- A step can use the sandbox while the session's turns use it, as subagents that share a sandbox
|
|
875
|
+
do. Give each one its own files to write.
|
|
876
|
+
- Steps run at least once and retry after a failure, so make sandbox writes safe to repeat. Write
|
|
877
|
+
whole files instead of appending, or check for earlier output first.
|
|
878
|
+
- When the session shares its parent's sandbox, the step opens it with the parent's sandbox
|
|
879
|
+
definition, and the parent removes it when the parent ends.
|
|
880
|
+
- A step runs wherever the workflow runs. A sandbox on one machine's disk, such as just-bash, is
|
|
881
|
+
reachable from a step only on that machine, as in local development.
|
|
882
|
+
|
|
975
883
|
## Workflow tool examples
|
|
976
884
|
|
|
977
885
|
### Approve with a deadline and an escalation
|
|
@@ -996,9 +904,9 @@ async task({ service }, ctx) {
|
|
|
996
904
|
}
|
|
997
905
|
```
|
|
998
906
|
|
|
999
|
-
One
|
|
1000
|
-
conversation, and
|
|
1001
|
-
|
|
907
|
+
One question stays on the channel the whole time. As a `task`, the call doesn't hold the
|
|
908
|
+
conversation, and steering doesn't withdraw the question. `pageOnCall` is a step, and returning
|
|
909
|
+
withdraws the question.
|
|
1002
910
|
|
|
1003
911
|
### Wait for an external system to call back
|
|
1004
912
|
|
|
@@ -1025,9 +933,9 @@ export default defineWorkflowTool({
|
|
|
1025
933
|
```
|
|
1026
934
|
|
|
1027
935
|
`createWebhook` mints a URL under `/.well-known/workflow/v1/webhook/` that eve serves. The external
|
|
1028
|
-
system posts to it when it is done
|
|
1029
|
-
|
|
1030
|
-
|
|
936
|
+
system posts to it when it is done, and nothing runs in between. Use `createHook` with `resumeHook`
|
|
937
|
+
for a deterministic token. To customize the HTTP response, pass `respondWith: new Response(...)` to
|
|
938
|
+
`createWebhook`.
|
|
1031
939
|
|
|
1032
940
|
### Ask now, act when answered
|
|
1033
941
|
|
|
@@ -1058,29 +966,25 @@ export default defineWorkflowTool({
|
|
|
1058
966
|
});
|
|
1059
967
|
```
|
|
1060
968
|
|
|
1061
|
-
The turn
|
|
969
|
+
The turn waits while the approval card stays on the channel. When someone answers, the refund runs
|
|
1062
970
|
and the agent receives the outcome as the tool result.
|
|
1063
971
|
|
|
1064
972
|
## Semantics
|
|
1065
973
|
|
|
1066
|
-
|
|
1067
|
-
cancellation.
|
|
974
|
+
A workflow tool call ends once, with the return value, the error, or a cancellation.
|
|
1068
975
|
|
|
1069
|
-
While an `execute` call runs, the turn
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
turn, and steering never touches it.
|
|
976
|
+
While an `execute` call runs, the turn waits, and a message sent with `turnPolicy: "queue"` waits
|
|
977
|
+
for it. A task doesn't hold the turn. See [Stop early for a new message](#stop-early-for-a-new-message)
|
|
978
|
+
for `steer` messages.
|
|
1073
979
|
|
|
1074
980
|
Errors follow the SDK. A thrown error in a step retries per the step's policy; `FatalError` does
|
|
1075
|
-
not. An error that escapes the body fails the tool
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
Renaming or moving that function creates a new workflow. Runs in flight finish on the deployment that started them; a run that
|
|
1086
|
-
resumes on a deployment without its tool fails with an error naming the missing workflow.
|
|
981
|
+
not. An error that escapes the body fails the tool call.
|
|
982
|
+
|
|
983
|
+
An interrupted dispatch can start a second run for the same call, and both runs may execute. Use an
|
|
984
|
+
application idempotency key for side effects that must happen only once.
|
|
985
|
+
|
|
986
|
+
The workflow id comes from the entry point's module path and function name. Inline entry points use
|
|
987
|
+
the tool module and the name `execute`, `task`, or `serve`. Imported ones use their declaring module
|
|
988
|
+
and name. Renaming or moving that function creates a new workflow. Runs in flight finish on the
|
|
989
|
+
deployment that started them. A run that resumes on a deployment without its tool fails with an
|
|
990
|
+
error naming the missing workflow.
|