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/subagents/index.mdx
CHANGED
|
@@ -3,100 +3,80 @@ title: "Subagents"
|
|
|
3
3
|
description: "Delegate work to root-agent copies or declared specialists with their own tools and sandbox."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
A subagent is a specialist agent your agent can delegate work to. Each one lives under `agent/subagents/<name>/` with its own `agent.ts`. The parent model reads the subagent's `description` to decide when to delegate, sends it a message, and gets its reply back.
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Every subagent call runs as a [task](./tools/tasks). The call returns a
|
|
13
|
-
receipt naming the task's `taskId` right away, the child works while the parent continues, and the
|
|
14
|
-
child's final reply for that turn arrives as the task's result. The parent's turn does not end while
|
|
15
|
-
the task is working. If the child's turn fails, the call fails and the task ends. This applies to
|
|
16
|
-
root-agent copies, declared local subagents, and remote subagents. The subagent session remains
|
|
17
|
-
available for later calls with the same `taskId`. When an action must wait for a subagent's result,
|
|
18
|
-
such as publishing only after a review, [run both from one workflow tool](./tools/tasks#order-work-that-depends-on-a-result).
|
|
19
|
-
|
|
20
|
-
## The built-in `agent` tool
|
|
21
|
-
|
|
22
|
-
The root session receives `agent` by default. The model calls it to delegate a task to a new copy of the root agent or continue an existing copy:
|
|
23
|
-
|
|
24
|
-
```ts
|
|
25
|
-
{
|
|
26
|
-
message: string; // everything the child needs; it does not see the parent's history
|
|
27
|
-
taskId?: string; // continue an existing child
|
|
28
|
-
}
|
|
8
|
+
```text
|
|
9
|
+
agent/subagents/researcher/
|
|
10
|
+
├── agent.ts # required: description and model
|
|
11
|
+
└── instructions.md # optional system prompt
|
|
29
12
|
```
|
|
30
13
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
`agent` is intentionally root-only. Copies created by it cannot call `agent`, and declared subagents never receive the built-in tool. If a stale or forced recursive call reaches execution, eve rejects it instead of starting another child session.
|
|
34
|
-
|
|
35
|
-
The parent transfers data to the child through the `message` input it gives the subagent. Do not include sensitive data in a subagent request unless that child and its inherited tools, connections, sandbox, and telemetry path are appropriate for that data.
|
|
36
|
-
|
|
37
|
-
An authored workflow can open the same root-copy target through `ctx.agent("agent")`. To keep the copied configuration but use another model for that child session, pass a [model override to `ctx.agent`](./tools/workflows#delegate-work-ctxagent). The default model-facing tool does not accept a model choice; an authored [`agentWithModel` tool](./concepts/built-in-tools#agent) can expose that choice in its input.
|
|
38
|
-
|
|
39
|
-
To prevent the root session from delegating to a fresh copy of itself, set `tool: false` on the root agent:
|
|
40
|
-
|
|
41
|
-
```ts title="agent/agent.ts"
|
|
14
|
+
```ts title="agent/subagents/researcher/agent.ts"
|
|
42
15
|
import { defineAgent } from "eve";
|
|
43
16
|
|
|
44
17
|
export default defineAgent({
|
|
18
|
+
description: "Investigate ambiguous questions before the parent agent responds.",
|
|
45
19
|
model: "anthropic/claude-opus-5.5",
|
|
46
|
-
tool: false,
|
|
47
20
|
});
|
|
48
21
|
```
|
|
49
22
|
|
|
50
|
-
|
|
23
|
+
Use a subagent to give a task to a specialist with a different prompt or tools, or to run independent work in parallel. eve also has two other kinds:
|
|
51
24
|
|
|
52
|
-
|
|
25
|
+
- The [built-in `agent` tool](#the-built-in-agent-tool) starts a copy of the root agent that shares its sandbox and tools.
|
|
26
|
+
- A [remote agent](./guides/remote-agents) is a separately deployed eve agent, with its own configuration and authentication.
|
|
53
27
|
|
|
54
|
-
|
|
28
|
+
## Declared subagents
|
|
55
29
|
|
|
56
|
-
|
|
57
|
-
import { defineAgent } from "eve";
|
|
30
|
+
A declared subagent uses the same `defineAgent` helper as the root agent. Its name comes from its directory: `agent/subagents/researcher/` is the `researcher` tool. The parent model calls that tool with a message:
|
|
58
31
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
32
|
+
```ts
|
|
33
|
+
{
|
|
34
|
+
message: string; // everything the child needs; it never sees the parent's conversation
|
|
35
|
+
taskId?: string; // continue an earlier child instead of starting a new one
|
|
36
|
+
}
|
|
63
37
|
```
|
|
64
38
|
|
|
65
|
-
|
|
39
|
+
Each call runs as a [task](./tools/tasks). The parent keeps working, and the child's final reply arrives as the task's result. If the child fails, the call fails. When one action must wait for a subagent's result, such as publishing only after a review, [run both from one workflow tool](./tools/tasks#order-work-that-depends-on-a-result).
|
|
66
40
|
|
|
67
|
-
|
|
68
|
-
import { defineAgent } from "eve";
|
|
41
|
+
Rules:
|
|
69
42
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
});
|
|
75
|
-
```
|
|
43
|
+
- `description` is required; the build fails without it.
|
|
44
|
+
- `agent` is reserved for the built-in root copy, so rename a subagent at `agent/subagents/agent/`. Namespaced names such as `crm__agent` are valid.
|
|
45
|
+
- A subagent's directory can hold its own `instructions.md` (or `instructions.ts`), `tools/`, `connections/`, `skills/`, `extensions/`, `sandbox/`, `hooks/`, and nested `subagents/`. It can't have `channels/` or `schedules/`, which are root-only.
|
|
46
|
+
- A subagent can call its own nested subagents, to any depth.
|
|
76
47
|
|
|
77
|
-
|
|
48
|
+
To choose how the parent model sees the subagent, set `tool` in its `agent.ts`:
|
|
78
49
|
|
|
79
|
-
|
|
50
|
+
| `tool` | The parent model |
|
|
51
|
+
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
| omitted | Sees it as a tool. |
|
|
53
|
+
| `"deferred"` | Doesn't see it in its tool list, but can find it with [`eve__search`](/docs/concepts/built-in-tools#eve__search-eve__tool-and-eve__skill) and call it with `eve__tool`. Use this when a parent has many specialists. |
|
|
54
|
+
| `false` | Can't call it. An authored [workflow tool](/docs/tools/workflows) can still call it with `ctx.agent("researcher", ...)`. |
|
|
80
55
|
|
|
81
|
-
A
|
|
56
|
+
A tool file with the same name, such as `agent/tools/researcher.ts`, collides with the subagent and fails the build. To wrap the subagent in your own tool, set the subagent's `tool: false` and author the tool; `ctx.agent("researcher", ...)` still reaches the subagent. To hide it completely, export `disableTool()` from that path instead. When a dynamic subagent and a dynamic tool collide, eve logs the collision and skips that result.
|
|
82
57
|
|
|
83
|
-
A mounted extension can
|
|
58
|
+
A mounted extension can add subagents from its `extension/subagents/` directory, named with the mount's namespace: mounting an extension as `crm` adds its `reviewer` as `crm__reviewer`. See [Extensions](./extensions#add-a-subagent). An extension mounted under `subagents/<name>/extensions/` adds its tools, skills, and instructions only to that subagent:
|
|
84
59
|
|
|
85
|
-
|
|
60
|
+
```ts title="agent/subagents/researcher/extensions/search.ts"
|
|
61
|
+
export { default } from "@acme/research-search";
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Local `eve dev` also adds the bundled `self-modification__agent` subagent. Production builds don't include it. See [Self-Modification](/docs/guides/self-modification).
|
|
86
65
|
|
|
87
66
|
### Vercel workspace peers
|
|
88
67
|
|
|
89
|
-
In a Vercel agent workspace,
|
|
68
|
+
In a Vercel agent workspace, `defineWorkspaceAgent` from `eve/experimental/workspace` lets one member call another as a subagent. Add a file under the caller's `agent/subagents/`. The filename is the tool name, and `name` is the peer's directory under `agents/`:
|
|
90
69
|
|
|
91
70
|
```ts title="agents/foreman/agent/subagents/research.ts"
|
|
92
71
|
import { defineWorkspaceAgent } from "eve/experimental/workspace";
|
|
93
72
|
|
|
94
73
|
export default defineWorkspaceAgent({
|
|
95
|
-
name: "research",
|
|
74
|
+
name: "research", // must match a workspace member exactly
|
|
75
|
+
// description: omit to use the peer's own defineAgent description
|
|
96
76
|
});
|
|
97
77
|
```
|
|
98
78
|
|
|
99
|
-
|
|
79
|
+
Omit `transport` to use the built-in one. Local `vercel dev` routes calls without credentials, and on Vercel, calls reach the peer's `/eve/<name>` mount authenticated with the caller's Vercel OIDC token. Elsewhere, set a transport:
|
|
100
80
|
|
|
101
81
|
```ts title="agents/foreman/agent/subagents/research.ts"
|
|
102
82
|
import { defineWorkspaceAgent } from "eve/experimental/workspace";
|
|
@@ -111,15 +91,15 @@ export default defineWorkspaceAgent({
|
|
|
111
91
|
});
|
|
112
92
|
```
|
|
113
93
|
|
|
114
|
-
An explicit transport replaces the
|
|
94
|
+
An explicit transport replaces the default completely, and the peer's channel authentication must accept its credentials. Set `forwardPrincipal: true` only when the peer trusts the caller to pass along the user's identity; see [Remote agents](./guides/remote-agents#forward-the-callers-identity).
|
|
115
95
|
|
|
116
|
-
|
|
96
|
+
`defineWorkspaceAgent` and its `WorkspaceAgentDefinition` and `WorkspaceAgentTransport` types are experimental and have no compatibility promise. The `agents/<name>/` workspace layout and the `eve/vercel` integration are stable.
|
|
97
|
+
|
|
98
|
+
To start every member locally, run `vercel dev --local` with a root `vercel.ts` composed by `withEve`. `eve dev` starts only the selected agent, so use an explicit transport to reach a peer you run separately.
|
|
117
99
|
|
|
118
100
|
### Conditional availability
|
|
119
101
|
|
|
120
|
-
To
|
|
121
|
-
`defineDynamic` from that subagent's `agent.ts`. Return a `defineAgent`
|
|
122
|
-
configuration to expose the subagent, or `null` to omit it from the parent's tools.
|
|
102
|
+
To offer a subagent only to some sessions or turns, export `defineDynamic` from its `agent.ts`. Return a `defineAgent` configuration to offer it, or `null` to hide it from the parent model:
|
|
123
103
|
|
|
124
104
|
```ts title="agent/subagents/researcher/agent.ts"
|
|
125
105
|
import { defineAgent, defineDynamic } from "eve";
|
|
@@ -134,13 +114,7 @@ export default defineDynamic((ctx) =>
|
|
|
134
114
|
);
|
|
135
115
|
```
|
|
136
116
|
|
|
137
|
-
eve
|
|
138
|
-
removes the subagent's description and tool definition from the model-visible
|
|
139
|
-
surface. The subagent's filesystem manifest is always compiled; a non-nullish
|
|
140
|
-
result injects the returned agent configuration when the child runs.
|
|
141
|
-
|
|
142
|
-
Packaging controls must be available at compile time. `defineDynamic` takes only a function;
|
|
143
|
-
put packaging configuration on the root agent instead:
|
|
117
|
+
eve runs the function before each parent model call. The subagent's files are always built. Build settings such as `build.externalDependencies` can't be dynamic, so set them on the root agent, where they also apply to subagents:
|
|
144
118
|
|
|
145
119
|
```ts title="agent/agent.ts"
|
|
146
120
|
import { defineAgent } from "eve";
|
|
@@ -151,100 +125,87 @@ export default defineAgent({
|
|
|
151
125
|
});
|
|
152
126
|
```
|
|
153
127
|
|
|
154
|
-
|
|
155
|
-
See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for
|
|
156
|
-
when eve evaluates a subagent, failure behavior, and the dispatch-time guard.
|
|
128
|
+
See [Dynamic capabilities](./guides/dynamic-capabilities#dynamic-subagents) for when eve runs the function and what happens when it fails.
|
|
157
129
|
|
|
158
|
-
|
|
130
|
+
## The isolation boundary
|
|
159
131
|
|
|
160
|
-
|
|
161
|
-
agent/subagents/researcher/
|
|
162
|
-
├── agent.ts # required
|
|
163
|
-
├── instructions.md # or instructions.ts, optional
|
|
164
|
-
├── tools/ # optional, its own tools
|
|
165
|
-
├── extensions/ # optional, mounted only into this subagent
|
|
166
|
-
├── skills/ # optional, its own skills
|
|
167
|
-
├── sandbox/ # optional, its own sandbox + workspace seed
|
|
168
|
-
└── subagents/ # optional, nested subagents
|
|
169
|
-
```
|
|
132
|
+
A declared subagent inherits nothing from the root agent. It has only what you put under `agent/subagents/<name>/`, and anything it doesn't define falls back to eve's default, never to the root's version.
|
|
170
133
|
|
|
171
|
-
|
|
134
|
+
| What | Copy from the built-in `agent` tool | Declared subagent |
|
|
135
|
+
| ------------ | ----------------------------------- | -------------------------------------- |
|
|
136
|
+
| Instructions | The root's | Its own `instructions.{md,ts}` |
|
|
137
|
+
| Tools | The root's, except `agent` | Its own `tools/` |
|
|
138
|
+
| Connections | The root's | Its own `connections/` |
|
|
139
|
+
| Skills | The root's | Its own `skills/` |
|
|
140
|
+
| Sandbox | The root's sandbox, shared | Its own `sandbox/`, else eve's default |
|
|
141
|
+
| Hooks | The root's | Its own `hooks/` |
|
|
142
|
+
| Extensions | The root's | Its own `extensions/` |
|
|
143
|
+
| State | Starts empty | Starts empty |
|
|
144
|
+
| Channels | Root only | Root only |
|
|
145
|
+
| Schedules | Root only | Root only |
|
|
172
146
|
|
|
173
|
-
|
|
174
|
-
export { default } from "@acme/research-search";
|
|
175
|
-
```
|
|
147
|
+
To share a procedure between subagents, package the skill in a [workspace extension](./extensions#use-an-extension-in-a-workspace) and mount it in each. Share typed helpers through `lib/`.
|
|
176
148
|
|
|
177
|
-
The
|
|
149
|
+
The parent passes only the `message` to a child. Don't include sensitive data unless the child's tools, connections, sandbox, and telemetry are fit for it. Delegation isn't an approval boundary: protect sensitive tools with `approval`, connection approval, or route and session authorization wherever they can be called.
|
|
178
150
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
## The isolation boundary
|
|
182
|
-
|
|
183
|
-
A declared subagent inherits nothing from the root's authored slots. Discovery treats its directory as its own agent root, so it has only the instructions, tools, connections, skills, sandbox, hooks, and nested subagents authored under `agent/subagents/<id>/`. For a slot with a framework default, eve selects that source when the subagent does not author a replacement; it never inherits the root's authored version.
|
|
151
|
+
## Agent messaging
|
|
184
152
|
|
|
185
|
-
|
|
186
|
-
| ------------ | ----------------------------- | -------------------------------------- |
|
|
187
|
-
| Instructions | Inherited (copy of the agent) | Own `instructions.{md,ts}`, optional |
|
|
188
|
-
| Tools | Inherited except root-only | Own `tools/` |
|
|
189
|
-
| Connections | Inherited | Own `connections/` |
|
|
190
|
-
| Skills | Inherited | Own `skills/` |
|
|
191
|
-
| Sandbox | Reuses the parent sandbox | Own `sandbox/`, else framework default |
|
|
192
|
-
| Hooks | Inherited | Own `hooks/` |
|
|
193
|
-
| Extensions | Inherited contributions | Own `extensions/` |
|
|
194
|
-
| State | Fresh | Fresh |
|
|
195
|
-
| Channels | Root-only | Root-only |
|
|
196
|
-
| Schedules | Root-only | Root-only |
|
|
153
|
+
After it answers, a child waits with its conversation intact. To continue it in any later turn, call the same subagent tool with the child's `taskId` and a new `message`. Omit `taskId` to start a new child. A `taskId` for a task that ended, or that belongs to another tool, fails with `UNKNOWN_TASK`.
|
|
197
154
|
|
|
198
|
-
|
|
155
|
+
- **Correct work in progress:** call with the `taskId` of a working child. The message joins the child's current turn, or starts its next turn if the current one ends first, and one reply answers both calls.
|
|
156
|
+
- **Cancel:** call `eve__task_cancel` with the `taskId`, or cancel the turn that called the child. Start a new task to delegate again.
|
|
157
|
+
- **Find a child:** a `[Tasks]` note in the conversation lists working and idle tasks by `taskId` and tool.
|
|
199
158
|
|
|
200
|
-
|
|
159
|
+
Each message runs with the sender's auth. eve shuts down each child when the parent session ends or the task is cancelled. Shutdown is best effort: an unreachable child can keep running. For [remote agents](./guides/remote-agents), continuing and shutting down a child need both deployments to run an eve version that supports them.
|
|
201
160
|
|
|
202
|
-
|
|
161
|
+
See [Tasks](./tools/tasks) for how the model waits for, corrects, and cancels tasks.
|
|
203
162
|
|
|
204
163
|
## What the parent sees
|
|
205
164
|
|
|
206
|
-
|
|
165
|
+
The subagent tool's description is the subagent's `description`, plus a note that the child doesn't see the conversation and that `taskId` continues a task. The model, approvals, logs, and evals all use the tool's name, such as `researcher` or `crm__reviewer`.
|
|
207
166
|
|
|
208
|
-
|
|
167
|
+
To require structured output, call the child from an authored workflow tool with [`ctx.agent(name)`](./tools/workflows#delegate-work-ctxagent) and pass `outputSchema` to `send()`.
|
|
209
168
|
|
|
210
|
-
|
|
169
|
+
Approvals, questions, and sign-ins from a child appear on the parent session, so the parent's channel can prompt for them. On text-only channels, typing an option of the first open prompt, such as `approve` or `deny`, answers that prompt; each message answers one prompt. A tool approval stays open until the child accepts the answer, because the child's approval policy decides who may answer.
|
|
211
170
|
|
|
212
|
-
|
|
171
|
+
Each child has its own session and stream. The parent stream records:
|
|
213
172
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
The tool's description is the subagent's `description` followed by a sentence telling the model that the agent does not see the conversation and that `taskId` continues an agent task.
|
|
173
|
+
| Event | Meaning |
|
|
174
|
+
| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
175
|
+
| `task.started` | The task started. |
|
|
176
|
+
| `call.started` | A call started. Later calls to the same child carry its `taskId`. |
|
|
177
|
+
| `child.opened` | The child session opened, with `owner`, agent `name`, `sessionId`, and `stream`. |
|
|
178
|
+
| `interaction.opened` / `interaction.settled` | A child's approval, question, or sign-in opened or finished. `origin` names the child. |
|
|
179
|
+
| `call.settled` | The call finished, with the child's reply as `output` or the failure as `error.message`. |
|
|
222
180
|
|
|
223
|
-
|
|
181
|
+
Later calls with the same `taskId` reach the same child without another `child.opened`, so match calls to a child by `taskId`. To follow a child's progress from a client, pass its `child.opened` event to [`session.agent()`](./guides/client/streaming#follow-a-subagent) and call `stream()`. For a remote child, the stream is proxied and authenticated by the parent. Channels that show activity list a child's tool calls under its progress item, on a best-effort basis.
|
|
224
182
|
|
|
225
|
-
|
|
183
|
+
A child's model calls retry temporary provider failures up to three times. A retry repeats only the failed model call; earlier tool results and sandbox work stay. With [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching), a retry can also repeat the tool calls in the current batch. When retries run out, the call fails once.
|
|
226
184
|
|
|
227
|
-
|
|
185
|
+
## The built-in `agent` tool
|
|
228
186
|
|
|
229
|
-
|
|
187
|
+
The root session gets an `agent` tool by default. It starts a copy of the root agent, or continues one with `taskId`, using the same `{ message, taskId? }` input as a declared subagent.
|
|
230
188
|
|
|
231
|
-
|
|
189
|
+
A copy uses the root's instructions, connections, auth, tools (except `agent`), and sandbox, so the root sees its file writes immediately. It starts with an empty conversation and state. Several copies can run at once, so give parallel copies separate files to write.
|
|
232
190
|
|
|
233
|
-
|
|
191
|
+
Only the root session has `agent`: copies and declared subagents can't call it. To run a copy on another model, call it from a workflow with [`ctx.agent("agent", { model })`](./tools/workflows#delegate-work-ctxagent), or offer the [`agentWithModel` tool](./concepts/built-in-tools#agent), which adds a `model` input.
|
|
234
192
|
|
|
235
|
-
|
|
193
|
+
To turn the tool off, set `tool: false` on the root agent:
|
|
236
194
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
A call with the `taskId` of a child that is still working joins the child's current turn, and that turn's final reply settles both calls. If the turn ends before the child reads the message, the message starts the child's next turn, and that turn's reply settles both calls. Use it to correct or add to work in progress. `eve__task_cancel` with the task's `taskId` ends the task and stops the child's current work. Start a new task to delegate again after a cancel.
|
|
195
|
+
```ts title="agent/agent.ts"
|
|
196
|
+
import { defineAgent } from "eve";
|
|
240
197
|
|
|
241
|
-
|
|
198
|
+
export default defineAgent({
|
|
199
|
+
model: "anthropic/claude-opus-5.5",
|
|
200
|
+
tool: false,
|
|
201
|
+
});
|
|
202
|
+
```
|
|
242
203
|
|
|
243
|
-
|
|
204
|
+
You can also export `disableTool()` from `agent/tools/agent.ts`, or author your own tool there, which takes priority over `tool: false`. Re-export `eve/tools/agent` from that path to keep the built-in tool. A workflow in a root session can still call the copy with `ctx.agent("agent", ...)`.
|
|
244
205
|
|
|
245
206
|
## When to split
|
|
246
207
|
|
|
247
|
-
|
|
208
|
+
Create a subagent when a task needs a different prompt or role, fewer tools, or its own sandbox. When the agent keeps its role and needs only an optional procedure, use a [skill](./skills) instead.
|
|
248
209
|
|
|
249
210
|
## What to read next
|
|
250
211
|
|