eve 0.89.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 +39 -9
- package/dist/src/channel/adapter.d.ts +12 -3
- package/dist/src/channel/adapter.js +1 -1
- package/dist/src/channel/auth/definitions.d.ts +7 -20
- package/dist/src/channel/auth/definitions.js +1 -1
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
- package/dist/src/channel/auth/jwt-hmac.js +1 -1
- package/dist/src/channel/auth/oidc.js +1 -1
- package/dist/src/channel/auth/result.d.ts +2 -3
- package/dist/src/channel/auth/result.js +1 -1
- package/dist/src/channel/channel-address.d.ts +1 -1
- package/dist/src/channel/channel-address.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/schedule.js +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
- package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
- package/dist/src/cli/dev/environment.js +1 -1
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
- package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
- package/dist/src/cli/dev/tui/runner.js +2 -2
- package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
- package/dist/src/cli/dev/tui/status-line.js +1 -1
- package/dist/src/client/agent-info-schema.d.ts +341 -326
- package/dist/src/client/agent-info-schema.js +1 -1
- package/dist/src/client/agent-info-types.d.ts +13 -10
- package/dist/src/client/client-error.d.ts +1 -1
- package/dist/src/client/client.d.ts +5 -3
- package/dist/src/client/client.js +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/evals/target.js +1 -1
- package/dist/src/eve-channel/auth.d.ts +19 -0
- package/dist/src/eve-channel/auth.js +1 -0
- package/dist/src/eve-channel/index.d.ts +1 -0
- package/dist/src/eve-channel/index.js +1 -1
- package/dist/src/eve-channel/types.d.ts +23 -4
- package/dist/src/execution/catalog/connection-entry.js +1 -1
- package/dist/src/execution/coordination-dispatch-shared.js +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/internal/authored-module-graph.js +1 -1
- package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
- package/dist/src/protocol/routes.d.ts +7 -1
- package/dist/src/protocol/routes.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/github/githubChannel.js +1 -1
- package/dist/src/public/channels/github/state.d.ts +7 -0
- package/dist/src/public/channels/github/state.js +1 -1
- package/dist/src/public/channels/mcp.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/channels/telegram/telegramChannel.js +1 -1
- package/dist/src/public/connections/index.d.ts +1 -1
- package/dist/src/public/definitions/channel.js +1 -1
- package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
- 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/frame.js +1 -1
- 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/channels/registry.d.ts +2 -2
- package/dist/src/runtime/channels/registry.js +1 -1
- package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
- package/dist/src/runtime/connections/approval-scope.js +1 -0
- package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
- package/dist/src/runtime/connections/mcp-client.js +1 -1
- package/dist/src/runtime/connections/provided-arguments.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/agent-info-access.d.ts +5 -0
- package/dist/src/shared/agent-info-access.js +1 -0
- package/dist/src/shared/connection-types.d.ts +21 -4
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/svelte/index.js +1 -1
- package/dist/src/svelte/use-eve-agent.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/dist/src/vue/index.js +1 -1
- package/dist/src/vue/use-eve-agent.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +265 -280
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -204
- 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 -194
- 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 +205 -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 +17 -18
- 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 +100 -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 +47 -41
- 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/prepare-for-1-0.md +23 -1
- 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/overview.mdx
CHANGED
|
@@ -4,130 +4,180 @@ description: "Define typed actions the agent can call, and gate sensitive ones o
|
|
|
4
4
|
url: /tools
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file.
|
|
7
|
+
A tool is a typed action the agent can call, such as hitting an API, running a query, or writing a file. Each tool is a file under `agent/tools/`, and the filename is the tool name the model sees. Define a tool when you implement the action in code you control.
|
|
8
8
|
|
|
9
9
|
## Define a tool
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
```text
|
|
12
|
+
agent/
|
|
13
|
+
├── agent.ts
|
|
14
|
+
└── tools/
|
|
15
|
+
└── get_weather.ts # the model calls this tool `get_weather`
|
|
16
|
+
```
|
|
12
17
|
|
|
13
18
|
```ts title="agent/tools/get_weather.ts"
|
|
14
19
|
import { defineTool } from "eve/tools";
|
|
15
20
|
import { z } from "zod";
|
|
16
21
|
|
|
17
22
|
export default defineTool({
|
|
23
|
+
// required: what the tool does, written for the model
|
|
18
24
|
description: "Get the current weather for a city.",
|
|
25
|
+
// required: use z.object({}) for a tool with no input
|
|
19
26
|
inputSchema: z.object({ city: z.string().min(1) }),
|
|
27
|
+
// required: may be sync, async, or an async generator
|
|
20
28
|
async execute({ city }, ctx) {
|
|
21
29
|
return { city, condition: "Sunny", temperatureF: 72 };
|
|
22
30
|
},
|
|
23
31
|
});
|
|
24
32
|
```
|
|
25
33
|
|
|
26
|
-
|
|
34
|
+
- Tools run in your app runtime, not in the [sandbox](/docs/sandbox). They can read `process.env` and import shared code from `lib/`.
|
|
35
|
+
- `inputSchema` is a Zod schema, any Standard Schema, or a plain JSON Schema object. Zod and Standard Schema infer the `input` type, and a plain JSON Schema types it as `Record<string, unknown>`.
|
|
36
|
+
- eve validates the input before `execute` runs. Zod and Standard Schema use their own library, so any installed Zod version works.
|
|
37
|
+
- eve sends a plain JSON Schema to the model without its `$schema` keyword. It validates with JSON Schema 2020-12 rules, which cover draft-07 keywords.
|
|
38
|
+
- For a JSON Schema, eve fills omitted properties from their `default` values. `format` is an annotation only.
|
|
39
|
+
- An unknown `type` name or an unresolvable `$ref` stops eve from checking a JSON Schema. The model still receives the schema, and `execute` gets the input unchecked.
|
|
40
|
+
- Optional input fields stay optional, because eve turns off provider strict mode for function tools.
|
|
41
|
+
- Tool outputs must be JSON-serializable. Convert `Date`, `Map`, `Set`, `NaN`, and cyclic values before you return them.
|
|
42
|
+
- Add an `outputSchema` for structured output. With Zod or Standard Schema, it also types the `execute` return.
|
|
43
|
+
- Schemas can come from helper modules and be composed with Zod.
|
|
27
44
|
|
|
28
|
-
|
|
29
|
-
- a `description`: what the tool does, written for the model.
|
|
30
|
-
- an `inputSchema`: a Zod schema (or any Standard Schema, or a plain JSON Schema object). Required. For no input, pass `z.object({})`. Zod and Standard Schema infer the `input` type in `execute`. Plain JSON Schema types it as `Record<string, unknown>`.
|
|
31
|
-
- an `execute(input, ctx)`: the implementation. May be sync, async, or an async generator.
|
|
45
|
+
### The `ctx` parameter
|
|
32
46
|
|
|
33
|
-
|
|
47
|
+
`execute` gets a `ctx` with these accessors:
|
|
34
48
|
|
|
35
|
-
|
|
49
|
+
- `ctx.session`: session metadata, turn, auth, and parent agent.
|
|
50
|
+
- `ctx.callId`: the call's id, also on its [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
|
|
51
|
+
- `ctx.toolName`: the name the model called, with any namespace prefix.
|
|
52
|
+
- `ctx.messages`: the model input for the step that requested this call, as a [dynamic tool's](/docs/guides/dynamic-capabilities) `ctx.messages()` sees it.
|
|
53
|
+
- `ctx.abortSignal`: aborts when the turn is cancelled. Pass it to work that supports cancellation. Sandbox sessions from `ctx.getSandbox()` already use it.
|
|
54
|
+
- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
|
|
55
|
+
- `ctx.channel`: the channel serving the session, as [hooks](/docs/guides/hooks) and [dynamic resolvers](/docs/guides/dynamic-capabilities) see it: `kind`, `continuationToken`, and `metadata`. `metadata` is what the channel's `metadata(state)` hook returns, such as a Slack thread's `channelId` and `threadTs`.
|
|
56
|
+
- `ctx.to(channel, target)`: starts or continues a session on one of the agent's channels. See [Start channel sessions](#start-channel-sessions-ctxto).
|
|
36
57
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
58
|
+
## Options
|
|
59
|
+
|
|
60
|
+
| Field | Default | What it does |
|
|
61
|
+
| ---------------------- | ------------------ | ----------------------------------------------------------------------------- |
|
|
62
|
+
| `description` | required | Tells the model what the tool does. |
|
|
63
|
+
| `inputSchema` | required | Validates and types the model's input. |
|
|
64
|
+
| `execute` | required | Runs the tool. |
|
|
65
|
+
| `outputSchema` | none | Describes and types the return value. |
|
|
66
|
+
| `approval` | `never()` | [Asks a person to approve calls](#gate-a-tool-on-human-approval). |
|
|
67
|
+
| `toModelOutput` | full return | [Changes what the model sees](#shape-what-the-model-sees-with-tomodeloutput). |
|
|
68
|
+
| `label` | readable tool name | [Sets activity text](#label-tool-activity). |
|
|
69
|
+
| `endsTurn` | `false` | [Ends the turn after success](#end-the-turn-after-a-tool-call). |
|
|
70
|
+
| `deferred` | `false` | [Leaves the tool out of the tool list](#keep-a-tool-out-of-the-tool-list). |
|
|
71
|
+
| `availableInSubagents` | `true` | [Offers the tool in delegated sessions](#hide-a-tool-from-delegated-agents). |
|
|
41
72
|
|
|
42
|
-
|
|
73
|
+
## When a tool throws
|
|
43
74
|
|
|
44
|
-
|
|
75
|
+
If `execute` throws, the call ends with `call.settled` `outcome: "failed"`, and the model gets the error. It can respond, try something else, or call the tool again. eve never retries a tool itself, whatever the exception type, HTTP status, or `retryable` property.
|
|
45
76
|
|
|
46
|
-
|
|
77
|
+
Retry inside the tool when the operation is safe to repeat. Otherwise, return or throw an error that tells the model what to do. In-tool retries don't protect a write, because the model can make a fresh call with a new tool-call ID. Authored workflow steps have their own retries.
|
|
78
|
+
|
|
79
|
+
Protect non-idempotent operations, such as charges or emails, with the strongest mechanism the service supports:
|
|
80
|
+
|
|
81
|
+
1. Pass a stable idempotency key to the upstream API.
|
|
82
|
+
2. Otherwise, record a unique application operation before writing, and check it on every attempt.
|
|
83
|
+
3. Use human approval when a person must authorize each execution. Approval doesn't replace deduplication after an unclear network result.
|
|
84
|
+
|
|
85
|
+
After a crash, completed steps replay their saved result, and an interrupted step runs again. A call that the step already started doesn't run again. The model reads that the call may have taken effect and decides whether to repeat it. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
|
|
86
|
+
|
|
87
|
+
For one-way provider notifications, see [Durable cross-channel notifications](/docs/patterns/durable-cross-channel-notifications).
|
|
88
|
+
|
|
89
|
+
## Gate a tool on human approval
|
|
90
|
+
|
|
91
|
+
A tool can require a person to approve each call before it runs. Set `approval` with the helpers from `eve/tools/approval`:
|
|
92
|
+
|
|
93
|
+
```ts title="agent/tools/refund_charge.ts"
|
|
94
|
+
import { defineTool } from "eve/tools";
|
|
95
|
+
import { always } from "eve/tools/approval";
|
|
96
|
+
import { z } from "zod";
|
|
47
97
|
|
|
48
|
-
```ts title="agent/tools/coordinator.ts"
|
|
49
98
|
export default defineTool({
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
execute(
|
|
54
|
-
return
|
|
99
|
+
description: "Refund a charge.",
|
|
100
|
+
inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
|
|
101
|
+
approval: always(), // or auto() / once() / never() / a policy
|
|
102
|
+
async execute(input) {
|
|
103
|
+
return refund(input);
|
|
55
104
|
},
|
|
56
105
|
});
|
|
57
106
|
```
|
|
58
107
|
|
|
59
|
-
|
|
108
|
+
See [Human-in-the-loop](./human-in-the-loop) for the `auto`, `always`, `once`, and `never` helpers, input-dependent policies, and how a call waits for approval.
|
|
60
109
|
|
|
61
|
-
|
|
110
|
+
## Shape what the model sees with `toModelOutput`
|
|
62
111
|
|
|
63
|
-
|
|
112
|
+
Omit `toModelOutput` to give the model the full `execute` return. When a channel needs rich data but the model needs only the gist, return a smaller value:
|
|
64
113
|
|
|
65
|
-
```ts
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
inputSchema: z.object({ reportId: z.string() }),
|
|
70
|
-
execute({ reportId }) {
|
|
71
|
-
return exportReport(reportId);
|
|
72
|
-
},
|
|
73
|
-
});
|
|
114
|
+
```ts
|
|
115
|
+
toModelOutput(output) {
|
|
116
|
+
return { type: "text", value: `Report for ${output.domain}: score ${output.score}.` };
|
|
117
|
+
},
|
|
74
118
|
```
|
|
75
119
|
|
|
76
|
-
|
|
120
|
+
`toModelOutput` receives the typed `execute` return and changes only what the model sees. Channel handlers and hooks still get the full output on `call.settled`, so a channel can render Slack Block Kit the model never sees.
|
|
77
121
|
|
|
78
|
-
|
|
122
|
+
Return `{ type: "text", value }` for a summary or `{ type: "json", value }` for a smaller, JSON-serializable object.
|
|
79
123
|
|
|
80
|
-
|
|
124
|
+
Do not return secrets, credentials, unnecessary personal data, or unbounded sensitive content from tools. Filter, minimize, and redact tool outputs before you return them.
|
|
81
125
|
|
|
82
|
-
###
|
|
126
|
+
### Send images to the model with content parts
|
|
83
127
|
|
|
84
|
-
|
|
128
|
+
To give a vision-capable model an image, such as a screenshot or chart, return a `content` output from `toModelOutput`. Build outputs with `toolOutput` and parts with `toolOutputPart`, both from `eve/tools`:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import { defineTool, toolOutput, toolOutputPart } from "eve/tools";
|
|
85
132
|
|
|
86
|
-
```ts title="agent/tools/react.ts"
|
|
87
133
|
export default defineTool({
|
|
88
|
-
description: "
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
134
|
+
description: "Capture a screenshot of the current page",
|
|
135
|
+
inputSchema: z.object({ url: z.string() }),
|
|
136
|
+
async execute(input) {
|
|
137
|
+
const png = await captureScreenshot(input.url);
|
|
138
|
+
return { path: png.path, screenshotBase64: png.base64 };
|
|
139
|
+
},
|
|
140
|
+
toModelOutput(output) {
|
|
141
|
+
return toolOutput.content([
|
|
142
|
+
toolOutputPart.text(`Screenshot of ${output.path}:`),
|
|
143
|
+
// file payloads must be base64 strings
|
|
144
|
+
toolOutputPart.file(output.screenshotBase64, { mediaType: "image/png" }),
|
|
145
|
+
]);
|
|
94
146
|
},
|
|
95
147
|
});
|
|
96
148
|
```
|
|
97
149
|
|
|
98
|
-
|
|
150
|
+
`toolOutput.text` and `toolOutput.json` build the other two shapes, and hand-written literals also work. eve warns above 3 MiB. A model without vision support fails with its provider's error.
|
|
99
151
|
|
|
100
|
-
|
|
101
|
-
Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
|
|
102
|
-
```
|
|
152
|
+
eve writes each returned file to the session sandbox and keeps a reference in session history. Every later model call sends the file again, so it stays visible on later turns. See [Inbound attachments](/docs/sandbox#inbound-attachments).
|
|
103
153
|
|
|
104
|
-
|
|
154
|
+
When compaction drops older tool results, each file becomes a text reference such as `Attached file /workspace/.eve/attachments/<hash>/chart.png (image/png)`. The built-in `read_file` tool can open it again. It shows the model PNG, JPEG, GIF, and WebP images up to 3 MiB and PDFs up to 20 MiB.
|
|
105
155
|
|
|
106
|
-
|
|
156
|
+
#### Send a file by URL
|
|
107
157
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
}
|
|
158
|
+
For a large file in object storage, such as a PDF behind a presigned S3 link, return its URL with `toolOutputPart.fileUrl`:
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
toModelOutput(output) {
|
|
162
|
+
return toolOutput.content([
|
|
163
|
+
toolOutputPart.text(`Contract ${output.id}:`),
|
|
164
|
+
// only https: URLs are accepted
|
|
165
|
+
toolOutputPart.fileUrl(output.signedUrl, { mediaType: "application/pdf" }),
|
|
166
|
+
]);
|
|
167
|
+
},
|
|
118
168
|
```
|
|
119
169
|
|
|
120
|
-
|
|
170
|
+
eve keeps only the URL in session history and doesn't write the file to the sandbox. The provider fetches the URL when it supports that file type. Otherwise, your app runtime downloads the file before the call.
|
|
121
171
|
|
|
122
|
-
|
|
172
|
+
Every later model call sends the URL again, so it must stay readable for the whole session. The provider counts the file's input tokens on each call, as for an inline file.
|
|
123
173
|
|
|
124
|
-
|
|
174
|
+
When compaction drops the tool result, the file becomes `Attached file <filename> (<mediaType>)`, and the URL is gone. Also return a text part with an id or path, so the tool can fetch the file again later.
|
|
125
175
|
|
|
126
|
-
|
|
176
|
+
## More tool options
|
|
127
177
|
|
|
128
178
|
### Label tool activity
|
|
129
179
|
|
|
130
|
-
Use `label.start(input)` to describe a call in
|
|
180
|
+
Use `label.start(input)` to describe a call in the activity users see. The callback receives the validated input:
|
|
131
181
|
|
|
132
182
|
```ts title="agent/tools/deploy.ts"
|
|
133
183
|
export default defineTool({
|
|
@@ -145,17 +195,17 @@ export default defineTool({
|
|
|
145
195
|
});
|
|
146
196
|
```
|
|
147
197
|
|
|
148
|
-
The label
|
|
198
|
+
The label changes only what users see, not the tool name, input, or behavior. eve records it on the call's public action event, so channels show `Deploy storefront to production` and stream consumers can read it. If the callback throws or returns an empty label, activity shows the tool name in readable form, such as `Sync accounts` for `sync_accounts`.
|
|
149
199
|
|
|
150
|
-
|
|
200
|
+
The provided `bash`, `glob`, `grep`, `read_file`, `web_fetch`, `web_search`, and `write_file` tools define labels. A deferred tool, agent, or connection tool called through [`eve__tool`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) shows its own label. Other built-in labels:
|
|
151
201
|
|
|
152
|
-
|
|
202
|
+
- An `eve__search` call shows `Search tools for “linear issues”`, then `Searched tools for “linear issues”, found 5`.
|
|
203
|
+
- A skill load shows `Load skill release-notes`, then `Loaded skill release-notes`.
|
|
204
|
+
- A connection's sign-in entry shows `Sign in to Linear`.
|
|
153
205
|
|
|
154
206
|
### Stream preliminary tool results
|
|
155
207
|
|
|
156
|
-
|
|
157
|
-
output snapshots before it finishes. Each `yield` replaces the previous snapshot; the final
|
|
158
|
-
yield is the normal tool result the model receives:
|
|
208
|
+
A `defineTool` executor written as an async generator sends complete output snapshots before it finishes. Each `yield` replaces the previous snapshot, and the final yield is the tool result:
|
|
159
209
|
|
|
160
210
|
```ts title="agent/tools/build_report.ts"
|
|
161
211
|
export default defineTool({
|
|
@@ -163,243 +213,185 @@ export default defineTool({
|
|
|
163
213
|
inputSchema: z.object({ project: z.string() }),
|
|
164
214
|
label: {
|
|
165
215
|
start: ({ project }) => `Build report for ${project}`,
|
|
166
|
-
delta: (_input, partial) => partial.phase,
|
|
216
|
+
delta: (_input, partial) => partial.phase, // runs for each snapshot
|
|
167
217
|
complete: (_input, output) => `Report ready with ${output.report.sections.length} sections`,
|
|
168
218
|
},
|
|
169
219
|
async *execute({ project }) {
|
|
170
220
|
yield { phase: "Collecting sources", report: null };
|
|
171
221
|
const report = await buildReport(project);
|
|
172
|
-
yield { phase: "Complete", report };
|
|
222
|
+
yield { phase: "Complete", report }; // the tool result
|
|
173
223
|
},
|
|
174
224
|
});
|
|
175
225
|
```
|
|
176
226
|
|
|
177
|
-
|
|
178
|
-
writer is busy, eve may keep only the newest adjacent snapshot for a call. The
|
|
179
|
-
snapshot is visible to channels, hooks, and clients but never enters model
|
|
180
|
-
history or `toModelOutput`; only the final yield does. Treat snapshots as
|
|
181
|
-
last-write-wins by tool call id, not append-only progress. The durable runtime
|
|
182
|
-
can retry a step and replay overlapping snapshots. A generator `return` value is not used as
|
|
183
|
-
the result in this mode; yield the final output. Workflow generators have different result
|
|
184
|
-
rules, described under [yield and return](#yield-and-return).
|
|
185
|
-
|
|
186
|
-
Use `label.delta(input, partial)` to project preliminary snapshots into
|
|
187
|
-
user-facing activity, and `label.complete(input, output)` to describe successful
|
|
188
|
-
settlement differently. Both callbacks receive the validated input first and the typed value yielded by
|
|
189
|
-
`execute` second. Each non-empty update replaces the previous activity label; the
|
|
190
|
-
result projection replaces the latest update immediately before eve marks the
|
|
191
|
-
action complete.
|
|
192
|
-
|
|
193
|
-
eve normalizes and bounds projected text before rendering it. If either
|
|
194
|
-
callback throws or returns an empty string, eve keeps the existing activity
|
|
195
|
-
label. `label.complete` does not run for failed or rejected tool calls. The
|
|
196
|
-
full values remain available in `call.progress` and `call.settled`; renderers
|
|
197
|
-
receive only the projected text.
|
|
198
|
-
|
|
199
|
-
### Durable waits
|
|
200
|
-
|
|
201
|
-
A tool call with an `execute` entry point finishes before the model continues. The definition
|
|
202
|
-
decides whether the executor can wait durably while the call is pending:
|
|
203
|
-
|
|
204
|
-
| Definition | Durable waits inside `execute` | Result delivered to the model |
|
|
205
|
-
| -------------------- | -------------------------------------------------------- | ---------------------------------- |
|
|
206
|
-
| `defineTool` | No; the executor runs inside the initiating step. | Executor output after it finishes. |
|
|
207
|
-
| `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
|
|
227
|
+
Channels, hooks, and clients see earlier yields as `call.progress` stream records. Only the final yield reaches model history and `toModelOutput`. eve ignores a generator's `return` value; see [Yield and return](#yield-and-return).
|
|
208
228
|
|
|
209
|
-
|
|
210
|
-
[task](/docs/tools/workflows#run-calls-as-tasks-task):
|
|
211
|
-
the call returns a receipt at once, and the workflow's output reaches the model later in a
|
|
212
|
-
`task.result` message. One that defines `serve(receive, ctx)` runs a
|
|
213
|
-
[resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more calls
|
|
214
|
-
by its `taskId`.
|
|
229
|
+
Keep the latest snapshot for each tool call id. eve may skip snapshots, and a retried step can send some again.
|
|
215
230
|
|
|
216
|
-
|
|
217
|
-
receipt at once, and the child's reply reaches the model later in a `task.result` message.
|
|
218
|
-
Inside an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent)
|
|
219
|
-
waits for the child's turn to end instead.
|
|
231
|
+
`label.delta(input, partial)` turns a snapshot into activity text, and `label.complete(input, output)` describes success. Each non-empty result replaces the current label. If a callback throws or returns an empty string, the label stays as it was. `label.complete` doesn't run for failed or rejected calls.
|
|
220
232
|
|
|
221
|
-
|
|
222
|
-
body, keep values needed after a wait in local variables; workflow replay reconstructs them across
|
|
223
|
-
durable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an
|
|
224
|
-
answer from the human.
|
|
233
|
+
Renderers receive only the label text. The full values stay in `call.progress` and `call.settled`.
|
|
225
234
|
|
|
226
235
|
### Yield and return
|
|
227
236
|
|
|
228
|
-
`yield`
|
|
229
|
-
It does not by itself create a durable wait for a person, timer, or external event. The value's
|
|
230
|
-
meaning depends on the executor:
|
|
237
|
+
`yield` doesn't make the tool wait for a person, timer, or external event. What a yielded value means depends on the executor:
|
|
231
238
|
|
|
232
239
|
| Executor | Ordinary `yield value` | Final output |
|
|
233
240
|
| -------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
234
241
|
| `defineTool` | Earlier values are `call.progress` snapshots; the final yield becomes the tool result. | Last yielded value; a generator `return` value is ignored. |
|
|
235
242
|
| `defineWorkflowTool` | Every yield is a `call.progress` snapshot. | Explicit return value; falls back to the last yield if the return is `null` or `undefined`, then to `null`. |
|
|
236
243
|
|
|
237
|
-
Progress snapshots
|
|
238
|
-
selected by the rules above becomes the tool result.
|
|
239
|
-
|
|
240
|
-
### Workflows as tools
|
|
241
|
-
|
|
242
|
-
Use `defineWorkflowTool` from `eve/tools` to run each call as a durable Workflow run. Its
|
|
243
|
-
executor must start with `"use workflow"` and receives `ctx.agent` and `ctx.ask`. The tool can
|
|
244
|
-
wait for a person, webhook, or timer without holding compute, then return its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and
|
|
245
|
-
examples.
|
|
244
|
+
Progress snapshots never enter model history. Only the final output does.
|
|
246
245
|
|
|
247
|
-
###
|
|
248
|
-
|
|
249
|
-
`execute` gets a `ctx` carrying the runtime accessors:
|
|
250
|
-
|
|
251
|
-
- `ctx.session`: session metadata, turn, auth, parent lineage.
|
|
252
|
-
- `ctx.callId`: the id of the current tool call, carried by the call's [stream events](/docs/concepts/sessions-runs-and-streaming) and approval context.
|
|
253
|
-
- `ctx.toolName`: the final runtime name the model called, including any namespace qualification.
|
|
254
|
-
- `ctx.messages`: the model input for the step that requested this call, the same messages a [dynamic capability's](/docs/guides/dynamic-capabilities) `ctx.messages()` returns before that call.
|
|
255
|
-
- `ctx.abortSignal`: aborts when the active turn is cancelled. Pass it to cancellation-aware work; sandbox sessions from `ctx.getSandbox()` are already bound to it.
|
|
256
|
-
- `ctx.getSandbox()`: the live [sandbox](/docs/sandbox) handle.
|
|
257
|
-
- `ctx.channel`: the channel serving the session, as [hooks](/docs/guides/hooks) and [dynamic resolvers](/docs/guides/dynamic-capabilities) read it: `kind`, `continuationToken`, and `metadata`, what the channel's `metadata(state)` hook projects, such as a Slack thread's `channelId` and `threadTs`.
|
|
258
|
-
- `ctx.to(channel, target)`: starts or continues a session on one of the agent's channels. See [Start channel sessions](#start-channel-sessions-ctxto).
|
|
259
|
-
|
|
260
|
-
Running in the app runtime is what lets a tool import shared code from `lib/`, read `process.env`, and take part in eve’s durable pause/resume model.
|
|
261
|
-
|
|
262
|
-
eve never runs authored tools during discovery. The model sees descriptors first, and only what it calls gets executed. Completed steps replay their recorded result. An interrupted step runs again from its checkpoint, but a call it already started does not run again: the model reads that the call may have taken effect, and decides whether to call it again.
|
|
263
|
-
|
|
264
|
-
Use operation-specific idempotency keys for external writes such as charges or emails. Approval records consent; it does not deduplicate an operation. See [Crash recovery](/docs/concepts/execution-model-and-durability#resuming-after-a-crash).
|
|
265
|
-
|
|
266
|
-
### Start channel sessions: `ctx.to`
|
|
267
|
-
|
|
268
|
-
`ctx.to(channel, target).send(message, options)` starts a session on one of the agent's channels, or continues the one at that target, through the channel's `receive` hook. It's the same call as a route handler's [cross-channel hand-off](/docs/channels/custom#cross-channel-hand-off), with the same [options](/docs/channels/custom#cross-channel-hand-off), and returns the delivery, whose `sessionId` names the session. Use it when the model decides that work should continue somewhere people can follow it, such as a new Slack thread:
|
|
246
|
+
### End the turn after a tool call
|
|
269
247
|
|
|
270
|
-
|
|
271
|
-
import { defineTool } from "eve/tools";
|
|
272
|
-
import { z } from "zod";
|
|
273
|
-
import slack from "../channels/slack";
|
|
248
|
+
Set `endsTurn: true` when a successful call is the whole answer, such as reacting to a message. eve ends the turn without calling the model again, so channels post no reply:
|
|
274
249
|
|
|
250
|
+
```ts title="agent/tools/react.ts"
|
|
275
251
|
export default defineTool({
|
|
276
|
-
description: "
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
auth: ctx.session.auth.current,
|
|
283
|
-
history: [{ role: "user", text: summary }],
|
|
284
|
-
idempotencyKey: `${ctx.session.id}:${ctx.callId}`,
|
|
285
|
-
});
|
|
286
|
-
return { sessionId: delivery.sessionId };
|
|
252
|
+
description: "React to the current message. Use this when a reaction is the whole answer.",
|
|
253
|
+
endsTurn: true,
|
|
254
|
+
inputSchema: z.object({ emoji: z.string() }),
|
|
255
|
+
async execute({ emoji }) {
|
|
256
|
+
await addReaction(emoji);
|
|
257
|
+
return { emoji };
|
|
287
258
|
},
|
|
288
259
|
});
|
|
289
260
|
```
|
|
290
261
|
|
|
291
|
-
|
|
292
|
-
- It runs the root agent with the `auth` you pass. Pass `ctx.session.auth.current` to start it as the caller.
|
|
293
|
-
- A tool call that retries runs the tool again. Pass `` idempotencyKey: `${ctx.session.id}:${ctx.callId}` ``, and the session at the target gets the message once. The destination session dedupes keys from every sender, and `ctx.callId` alone is unique only within the calling session, so include the session id. Built-in channels map a retry to the same session, including a Slack target with only a `channelId`. A platform post made before the session exists, such as an `initialMessage`, repeats.
|
|
294
|
-
- `ctx.to()` throws in a delegated session: a subagent, a root copy, or a remote agent call. A session it started would outlive the delegation and act for the caller, so return the result and send from a tool on the root agent.
|
|
262
|
+
eve adds this sentence, after a blank line, to the description the model sees:
|
|
295
263
|
|
|
296
|
-
|
|
264
|
+
```text
|
|
265
|
+
Calling this tool ends your turn once it succeeds: do not write a reply or call other tools in the same step. If it fails, you will see the error and can continue.
|
|
266
|
+
```
|
|
297
267
|
|
|
298
|
-
|
|
268
|
+
Leave the turn-ending rule out of `description`. `eve info` shows the description as you wrote it, without the added sentence.
|
|
299
269
|
|
|
300
|
-
|
|
270
|
+
To decide from the result, pass a function. eve calls it with the output of `execute` after each successful call, and the turn ends only when it returns or resolves to `true`:
|
|
301
271
|
|
|
302
|
-
|
|
272
|
+
```ts title="agent/tools/react.ts"
|
|
273
|
+
export default defineTool({
|
|
274
|
+
description:
|
|
275
|
+
"React to the current message. When the reaction posts, your turn ends; otherwise, reply in text.",
|
|
276
|
+
inputSchema: z.object({ emoji: z.string() }),
|
|
277
|
+
async execute({ emoji }) {
|
|
278
|
+
return { posted: await addReaction(emoji) };
|
|
279
|
+
},
|
|
280
|
+
// declare after execute so TypeScript infers `output`
|
|
281
|
+
endsTurn: (output) => output.posted,
|
|
282
|
+
});
|
|
283
|
+
```
|
|
303
284
|
|
|
304
|
-
|
|
285
|
+
If the function throws or rejects, eve logs a warning and treats the result as `false`. With an `outputSchema`, `output` takes that schema's type wherever `endsTurn` appears. eve doesn't add the sentence for a function, so say in `description` when the call ends the turn.
|
|
305
286
|
|
|
306
|
-
|
|
307
|
-
2. Otherwise, record a unique application operation before writing and check it on every attempt.
|
|
308
|
-
3. Use human approval when a person must authorize each execution, not as a substitute for deduplication after an ambiguous network result.
|
|
287
|
+
The turn ends only when every tool call in the step can end the turn, succeeds, and passes any `endsTurn` function. Otherwise, the model gets the results and continues. Channels don't post text the model wrote before the call as the reply. While [tasks](/docs/tools/tasks) are still working, the turn waits for them and then calls the model again.
|
|
309
288
|
|
|
310
|
-
|
|
289
|
+
eve ignores `endsTurn` in delegated sessions, which must reply to their caller, and on turns that request structured output. There, the model doesn't see the sentence, and eve doesn't call the function.
|
|
311
290
|
|
|
312
|
-
|
|
291
|
+
Dynamic tool entries accept both forms of `endsTurn`. `defineWorkflowTool` rejects it at build time. To end a turn without any other action, add the opt-in [`no_reply`](/docs/concepts/built-in-tools#no_reply) tool.
|
|
313
292
|
|
|
314
|
-
|
|
293
|
+
### Keep a tool out of the tool list
|
|
315
294
|
|
|
316
|
-
|
|
317
|
-
import { defineTool } from "eve/tools";
|
|
318
|
-
import { always } from "eve/tools/approval";
|
|
319
|
-
import { z } from "zod";
|
|
295
|
+
Set `deferred: true` for a tool the model rarely needs, or when an agent has too many tools to send in every request:
|
|
320
296
|
|
|
297
|
+
```ts title="agent/tools/export_report.ts"
|
|
321
298
|
export default defineTool({
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
return
|
|
299
|
+
deferred: true,
|
|
300
|
+
description: "Export a finished report as a PDF.",
|
|
301
|
+
inputSchema: z.object({ reportId: z.string() }),
|
|
302
|
+
execute({ reportId }) {
|
|
303
|
+
return exportReport(reportId);
|
|
327
304
|
},
|
|
328
305
|
});
|
|
329
306
|
```
|
|
330
307
|
|
|
331
|
-
|
|
308
|
+
eve leaves a deferred tool out of the tool list and doesn't name it in context. The model finds it with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and calls it with `eve__tool({ name: "export_report", input })`. Approvals, `endsTurn`, `toModelOutput`, hooks, and stream events then see `export_report`, as for a direct call.
|
|
332
309
|
|
|
333
|
-
|
|
310
|
+
The option works with `defineTool`, `defineWorkflowTool`, and dynamic tool entries. To defer an agent, set [`tool: "deferred"`](/docs/subagents#declared-subagents) on its `defineAgent` definition.
|
|
334
311
|
|
|
335
|
-
|
|
312
|
+
### Hide a tool from delegated agents
|
|
336
313
|
|
|
337
|
-
|
|
338
|
-
toModelOutput(output) {
|
|
339
|
-
return { type: "text", value: `Report for ${output.domain}: score ${output.score}.` };
|
|
340
|
-
},
|
|
341
|
-
```
|
|
314
|
+
Set `availableInSubagents: false` when only a top-level root session should call a tool:
|
|
342
315
|
|
|
343
|
-
|
|
316
|
+
```ts title="agent/tools/coordinator.ts"
|
|
317
|
+
export default defineTool({
|
|
318
|
+
availableInSubagents: false, // omit to offer the tool in every session
|
|
319
|
+
description: "Coordinate work that only the top-level root agent should start.",
|
|
320
|
+
inputSchema: z.object({ task: z.string() }),
|
|
321
|
+
execute({ task }) {
|
|
322
|
+
return coordinate(task);
|
|
323
|
+
},
|
|
324
|
+
});
|
|
325
|
+
```
|
|
344
326
|
|
|
345
|
-
|
|
327
|
+
The option works with `defineTool` and `defineWorkflowTool`. Copies of the root agent from the built-in `agent` tool don't get the tool. A declared subagent's own tool with this option is never offered, because a subagent always runs delegated. The option doesn't change a workflow's `ctx.agents` registry.
|
|
346
328
|
|
|
347
|
-
###
|
|
329
|
+
### Start channel sessions: `ctx.to`
|
|
348
330
|
|
|
349
|
-
|
|
331
|
+
`ctx.to(channel, target).send(message, options)` starts a session on one of the agent's channels, or continues the session at that target. It's the same call, with the same options, as a route handler's [cross-channel hand-off](/docs/channels/custom#cross-channel-hand-off). It returns the delivery, whose `sessionId` names the session. Use it when work should continue where people can follow it, such as a new Slack thread:
|
|
350
332
|
|
|
351
|
-
```ts
|
|
352
|
-
import { defineTool
|
|
333
|
+
```ts title="agent/tools/escalate.ts"
|
|
334
|
+
import { defineTool } from "eve/tools";
|
|
335
|
+
import { z } from "zod";
|
|
336
|
+
import slack from "../channels/slack";
|
|
353
337
|
|
|
354
338
|
export default defineTool({
|
|
355
|
-
description: "
|
|
356
|
-
inputSchema: z.object({
|
|
357
|
-
async execute(
|
|
358
|
-
const
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
339
|
+
description: "Hand this investigation to the on-call channel in Slack.",
|
|
340
|
+
inputSchema: z.object({ summary: z.string() }),
|
|
341
|
+
async execute({ summary }, ctx) {
|
|
342
|
+
const delivery = await ctx
|
|
343
|
+
.to(slack, { channelId: "C0123ABC" })
|
|
344
|
+
.send("Take over this investigation.", {
|
|
345
|
+
auth: ctx.session.auth.current, // start the session as the caller
|
|
346
|
+
history: [{ role: "user", text: summary }],
|
|
347
|
+
idempotencyKey: `${ctx.session.id}:${ctx.callId}`, // a retried call sends once
|
|
348
|
+
});
|
|
349
|
+
return { sessionId: delivery.sessionId };
|
|
366
350
|
},
|
|
367
351
|
});
|
|
368
352
|
```
|
|
369
353
|
|
|
370
|
-
The
|
|
354
|
+
- The new session belongs to the channel. People on that channel continue it, it has no parent, and it keeps running after the tool returns.
|
|
355
|
+
- It runs the root agent with the `auth` you pass.
|
|
356
|
+
- A retried tool call runs the tool again, so pass an `idempotencyKey` and the target session gets the message once. Include the session id, because the target session dedupes keys from every sender and `ctx.callId` is unique only within the calling session. Built-in channels map a retry to the same session, including a Slack target with only a `channelId`. A platform post made before the session exists, such as an `initialMessage`, repeats.
|
|
357
|
+
- `ctx.to()` throws in a delegated session, such as a subagent, a root copy, or a remote agent call. A session it started would outlive the delegation and act for the caller. Return the result instead, and send from a tool on the root agent.
|
|
371
358
|
|
|
372
|
-
|
|
359
|
+
See [Fork conversations into a new thread](/docs/patterns/fork-conversations-into-new-threads) for a tool that copies the current conversation into a new Slack thread.
|
|
373
360
|
|
|
374
|
-
|
|
361
|
+
### Workflows as tools
|
|
375
362
|
|
|
376
|
-
|
|
363
|
+
`defineWorkflowTool` from `eve/tools` runs each call as a Workflow run that survives restarts and redeploys. Its executor starts with `"use workflow"` and receives `ctx.agent` and `ctx.ask`. It can wait for a person, webhook, or timer without holding compute. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and examples.
|
|
377
364
|
|
|
378
|
-
|
|
365
|
+
### Durable waits
|
|
379
366
|
|
|
380
|
-
|
|
367
|
+
A tool call with an `execute` function finishes before the model continues. The definition decides whether the executor can pause and wait:
|
|
381
368
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
369
|
+
| Definition | Can wait inside `execute` | What the model receives |
|
|
370
|
+
| -------------------- | -------------------------------------------------------- | ---------------------------------- |
|
|
371
|
+
| `defineTool` | No; the executor runs inside the step that started it. | Executor output after it finishes. |
|
|
372
|
+
| `defineWorkflowTool` | Yes; the tool call waits while the workflow can suspend. | Workflow output after it finishes. |
|
|
373
|
+
|
|
374
|
+
A workflow tool that defines `task(input, ctx)` instead runs each call as a [task](/docs/tools/workflows#run-calls-as-tasks-task). The call returns a receipt at once, and the output arrives later in a `task.result` message. One that defines `serve(receive, ctx)` runs a [resumable task](/docs/tools/workflows#resumable-tasks-serve), which takes more calls by its `taskId`.
|
|
375
|
+
|
|
376
|
+
Subagent tools, whether built-in, declared, or remote, run as resumable tasks, so the child's reply also arrives in `task.result`. In an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent) waits for the child's turn to end instead.
|
|
377
|
+
|
|
378
|
+
In a workflow body, keep values needed after a wait in local variables, because workflow replay rebuilds them. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an answer from a person.
|
|
390
379
|
|
|
391
|
-
|
|
380
|
+
## Troubleshooting
|
|
392
381
|
|
|
393
|
-
|
|
382
|
+
| What you see | What to do |
|
|
383
|
+
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
384
|
+
| The build rejects `deferred` on a tool | Remove it from provider tools such as `webSearch()`, because the provider has to see their definition. |
|
|
385
|
+
| eve rejects a file part | Pass the file as a base64 string. Raw bytes (`Uint8Array`, `Buffer`) can't be saved as JSON. |
|
|
386
|
+
| Later model calls fail after a `fileUrl` part | Use a URL that stays readable for the whole session. A presigned URL that expires makes later calls fail. |
|
|
394
387
|
|
|
395
|
-
|
|
388
|
+
## When to use a connection or skill instead
|
|
396
389
|
|
|
397
|
-
|
|
390
|
+
To give the model tools from an external MCP or OpenAPI service, use a [connection](/docs/connections). For a written procedure the model loads only when needed, use a [skill](/docs/skills).
|
|
398
391
|
|
|
399
392
|
## What to read next
|
|
400
393
|
|
|
401
394
|
- [Human-in-the-loop](./human-in-the-loop): gate a tool on approval, or have the agent ask a question
|
|
402
|
-
- [Skills](/docs/skills): on-demand procedures the model loads when relevant
|
|
403
395
|
- [Built-in tools](/docs/concepts/built-in-tools): the default and opt-in framework tools and how to override or disable them
|
|
404
396
|
- [Dynamic capabilities](/docs/guides/dynamic-capabilities): tools whose set is resolved per session with `defineDynamic`
|
|
405
397
|
- [Authentication](/docs/guides/auth-and-route-protection): authenticate a tool to an external service
|