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
|
@@ -3,9 +3,9 @@ title: "Streaming"
|
|
|
3
3
|
description: "Consume eve client stream events live, reconnect by line position, and aggregate turn results."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
`ClientSession.send()`
|
|
6
|
+
A `Delivery` is the receipt `ClientSession.send()` returns once the server accepts a message. It carries a `sessionId` and `deliveryId` and doesn't wait for a reply. Call `result()` for its summary or `stream()` to watch it live. Each read is independent, and you can repeat either one. Import `Delivery` and its read types from `eve/sessions`.
|
|
7
7
|
|
|
8
|
-
Session controls return
|
|
8
|
+
Session controls return a `Delivery` too. `session.cancel({ turnId })` targets a turn you saw on the stream, so a late cancellation can't stop unrelated later work. Omit `turnId` to cancel the current work. For example, cancel as soon as this message reaches a turn:
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
11
|
const { session, delivery } = await client.sessions.create({ message: "Run the long operation." });
|
|
@@ -22,9 +22,9 @@ for await (const event of delivery.stream()) {
|
|
|
22
22
|
}
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
-
The cancellation
|
|
25
|
+
The cancellation's `result()` resolves once eve applies the cancel, even as a no-op for a turn that already ended. An idle session that hasn't ended also accepts cancellation instead of returning `no_active_turn`. Keep reading the original message's `Delivery` to see its outcome.
|
|
26
26
|
|
|
27
|
-
Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` removes model
|
|
27
|
+
Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` cancels a running turn and every working task, then removes the model's message history. It keeps the session and its other saved resources. Client `messages` and `transcriptOf()` then leave out everything before the clear. Await their results before you send another turn:
|
|
28
28
|
|
|
29
29
|
```ts
|
|
30
30
|
const compaction = await session.compact();
|
|
@@ -37,11 +37,11 @@ const cleared = await session.clear();
|
|
|
37
37
|
await cleared.result();
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
|
|
40
|
+
`context.settled` reports whether summarization succeeded; a failed or empty summary keeps the previous history. `session.end()` instead retires the session, and its `result()` resolves after the session is retired.
|
|
41
41
|
|
|
42
42
|
## Aggregate a turn
|
|
43
43
|
|
|
44
|
-
Use `result()` when you only
|
|
44
|
+
Use `result()` when you need only the final turn summary:
|
|
45
45
|
|
|
46
46
|
```ts
|
|
47
47
|
const response = await session.send("Summarize the latest forecast.");
|
|
@@ -53,37 +53,33 @@ console.log(result.outcome);
|
|
|
53
53
|
if (result.status === "failed") console.error(result.error.code, result.error.message);
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
turn that consumed it settles (`handled`), or when the turn pauses on an interaction
|
|
60
|
-
(`awaiting-input`), such as for an approval, question, or sign-in. See
|
|
56
|
+
`result()` reads until the `delivery.settled` event for the message's `deliveryId`. If the stream
|
|
57
|
+
ends first, the read rejects, even when the session has ended. That event arrives when the turn
|
|
58
|
+
finishes (`handled`) or pauses for an approval, question, or sign-in (`awaiting-input`). See
|
|
61
59
|
[authorization pauses](#authorization-pauses).
|
|
62
60
|
|
|
63
|
-
A turn that waits on its [tasks](/docs/tools/workflows#run-calls-as-tasks-task) stays open
|
|
64
|
-
`result()` keeps reading to its final reply
|
|
65
|
-
|
|
66
|
-
`
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
tool's question.
|
|
61
|
+
A turn that waits on its [tasks](/docs/tools/workflows#run-calls-as-tasks-task) stays open, and
|
|
62
|
+
`result()` keeps reading to its final reply; text written before the wait is narration. When a
|
|
63
|
+
call asks a question, such as a workflow tool's `ctx.ask()`, `result()` returns
|
|
64
|
+
`status: "awaiting-input"` with the question in `interactions`. Answer it with `respond()`, which
|
|
65
|
+
keeps reading the same turn. A question stays open until its `interaction.settled` event. The
|
|
66
|
+
session you answer on emits that event, even for a subagent's or workflow tool's question.
|
|
70
67
|
|
|
71
|
-
`result().status`
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
68
|
+
`result().status` is `awaiting-input`, `completed`, `failed`, or `cancelled`. A completed
|
|
69
|
+
request can leave its session open, so read `result().sessionEnded` to check whether the session
|
|
70
|
+
ended. Read `outcome` to tell an applied control from an ignored one. To inspect live progress, use
|
|
71
|
+
`delivery(view, deliveryId)` and, when it has a `turnId`, `turn(view, turnId)` from `eve/events`.
|
|
75
72
|
|
|
76
|
-
Results
|
|
77
|
-
`response.stream()` to your own collection.
|
|
78
|
-
|
|
73
|
+
Results don't collect an `events` array. To keep a request log, append events from
|
|
74
|
+
`response.stream()` to your own collection. Reads don't share a cursor, so a later
|
|
75
|
+
`response.result()` still reads the whole delivery.
|
|
79
76
|
|
|
80
|
-
`result()` closes
|
|
81
|
-
|
|
82
|
-
turns.
|
|
77
|
+
`result()` closes its HTTP stream, even when fetch instrumentation clones the response. The
|
|
78
|
+
session stays available for follow-up turns.
|
|
83
79
|
|
|
84
80
|
## Stream events live
|
|
85
81
|
|
|
86
|
-
|
|
82
|
+
Iterate `stream()` with `for await...of` to render progress:
|
|
87
83
|
|
|
88
84
|
```ts
|
|
89
85
|
const response = await session.send("Draft a plan and show your work.");
|
|
@@ -99,9 +95,9 @@ for await (const event of response.stream()) {
|
|
|
99
95
|
}
|
|
100
96
|
```
|
|
101
97
|
|
|
102
|
-
`content.delta` and `call.input`
|
|
98
|
+
`content.delta` and `call.input` carry only their new text. eve may merge adjacent deltas for the same part or call without changing the text or order.
|
|
103
99
|
|
|
104
|
-
The default message reducer accumulates
|
|
100
|
+
The default message reducer accumulates them for you. A raw consumer appends them by part:
|
|
105
101
|
|
|
106
102
|
```ts
|
|
107
103
|
const parts = new Map<string, string>();
|
|
@@ -112,13 +108,13 @@ for await (const event of response.stream()) {
|
|
|
112
108
|
}
|
|
113
109
|
```
|
|
114
110
|
|
|
115
|
-
After reconnecting without local state,
|
|
111
|
+
After reconnecting without local state, don't append a later delta to an empty value. Replay the earlier lines, or wait for the part's `content.completed`, which carries its whole value.
|
|
116
112
|
|
|
117
|
-
The
|
|
113
|
+
The client checks the stream version on every connection and accepts only version 27; a missing or different version fails the read.
|
|
118
114
|
|
|
119
115
|
## Handle event types
|
|
120
116
|
|
|
121
|
-
Import event types from `eve/client`, or the full catalog, the shared fold, and selectors from `eve/events`. Events read from a stream are `SessionStreamEvent`: a
|
|
117
|
+
Import event types from `eve/client`, or the full catalog, the shared fold, and selectors from `eve/events`. Events read from a stream are `SessionStreamEvent`: a recorded event or a progress update, with its `meta` envelope.
|
|
122
118
|
|
|
123
119
|
```ts
|
|
124
120
|
import type { SessionStreamEvent } from "eve/client";
|
|
@@ -152,27 +148,27 @@ The most common UI events are:
|
|
|
152
148
|
|
|
153
149
|
For the complete catalog, see [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
|
|
154
150
|
|
|
155
|
-
|
|
151
|
+
During `call.input`, the conversation's `tool` part has `state: "streaming"` and accumulates raw, possibly incomplete JSON in `inputText`. `call.requested` replaces it with the validated `input`.
|
|
156
152
|
|
|
157
|
-
A call to a tool that runs as a [task](/docs/tools/workflows#run-calls-as-tasks-task) starts with `call.started`
|
|
153
|
+
A call to a tool that runs as a [task](/docs/tools/workflows#run-calls-as-tasks-task) starts with a `call.started` that carries its `taskId`. It ends later with its own `call.settled`, and the model receives that result in its history.
|
|
158
154
|
|
|
159
|
-
File parts in `delivery.consumed.data.parts` never include raw bytes or internal sandbox paths
|
|
155
|
+
File parts in `delivery.consumed.data.parts` never include raw bytes or internal sandbox paths. They include `url` only for `http(s)` URLs; an inline file reports its `size` instead.
|
|
160
156
|
|
|
161
157
|
## Authorization pauses
|
|
162
158
|
|
|
163
|
-
A sign-in is an `interaction.opened` whose `request.kind` is `"sign-in"
|
|
159
|
+
A sign-in is an `interaction.opened` whose `request.kind` is `"sign-in"`: a connection needs OAuth or another authorization challenge before the turn can continue. Render the prompt from `request.signIn`, disable ordinary text input for that session, and persist the event with the chat history.
|
|
164
160
|
|
|
165
|
-
|
|
161
|
+
While the sign-in is pending, the stream emits `turn.paused`, and the current message's result returns `status: "awaiting-input"`. Completing the sign-in, or declining it, resumes the same session. Follow it with `session.stream()` to see the resumed work. To keep the prompt across a page refresh, save the session cursor and events, and restore them on load.
|
|
166
162
|
|
|
167
163
|
## Reconnection
|
|
168
164
|
|
|
169
|
-
HTTP
|
|
165
|
+
When an HTTP connection ends before the run does, the client reconnects from the next unread line without replaying events. Omit a policy to keep reconnecting until the message's work finishes or you abort the read. Use a session stream to follow work past that point. A stream ends for good on `{"$eve":"stream.ended"}`, which the server sends once the session has ended.
|
|
170
166
|
|
|
171
|
-
Browser network failures
|
|
167
|
+
Browser network failures also reconnect, both when opening a stream (`TypeError: Failed to fetch`, `TypeError: Load failed`, or `TypeError: NetworkError when attempting to fetch resource.`) and while reading the body (any `TypeError`, such as `TypeError: network error`). Invalid stream events still fail the read.
|
|
172
168
|
|
|
173
169
|
If your consumer persists events, key on `event.meta.position`. It is stable across reconnects and rewinds, so an overlapping replay is safe to ingest twice. See [Positions](../../concepts/sessions-runs-and-streaming#positions).
|
|
174
170
|
|
|
175
|
-
Set `reconnect: false` when a relay or proxy owns the cursor and reconnection
|
|
171
|
+
Set `reconnect: false` when a relay or proxy owns the cursor and reconnection. The client makes one stream GET and returns when that connection ends, without stopping the server-side turn:
|
|
176
172
|
|
|
177
173
|
```ts
|
|
178
174
|
const response = await session.send("Run the long operation.", {
|
|
@@ -205,7 +201,7 @@ const response = await session.send("Run the long operation.", {
|
|
|
205
201
|
|
|
206
202
|
## Open a stream manually
|
|
207
203
|
|
|
208
|
-
Use `session.stream()`
|
|
204
|
+
Use `session.stream()` to attach to an existing stream from a saved cursor:
|
|
209
205
|
|
|
210
206
|
```ts
|
|
211
207
|
const session = client.sessions.attach("wrun_01ARYZ6S41TSV4RRFFQ69G5FAV", {
|
|
@@ -234,11 +230,11 @@ for await (const event of session.stream({ startIndex: -1 })) {
|
|
|
234
230
|
}
|
|
235
231
|
```
|
|
236
232
|
|
|
237
|
-
Tail-relative
|
|
233
|
+
Tail-relative reads don't reconnect or advance the session's stored `streamIndex`. Break after the event you need.
|
|
238
234
|
|
|
239
235
|
## Bounded catch-up reads
|
|
240
236
|
|
|
241
|
-
Pass `follow: false` to read from the cursor to the
|
|
237
|
+
Pass `follow: false` to read from the cursor to the stream's current end and then stop, instead of following the live stream (the default):
|
|
242
238
|
|
|
243
239
|
```ts
|
|
244
240
|
for await (const event of session.stream({ follow: false })) {
|
|
@@ -247,9 +243,9 @@ for await (const event of session.stream({ follow: false })) {
|
|
|
247
243
|
// Returns once every line recorded before the stream opened is consumed.
|
|
248
244
|
```
|
|
249
245
|
|
|
250
|
-
The
|
|
246
|
+
The server reports that end when the first connection opens, and reconnects keep it. The stored `streamIndex` still advances, so a later `stream()` or `send()` picks up where the bounded read ended. When the cursor is already at or past that end, the iterator returns without yielding.
|
|
251
247
|
|
|
252
|
-
|
|
248
|
+
`follow: false` throws with a negative `startIndex`, because a tail-relative cursor can't be bounded. It also fails when the server doesn't report the stream's end, as an agent on an older eve version doesn't.
|
|
253
249
|
|
|
254
250
|
## Snapshot a session
|
|
255
251
|
|
|
@@ -263,20 +259,16 @@ const snapshot = await session.snapshot();
|
|
|
263
259
|
// snapshot.events holds lines 0 through snapshot.session.streamIndex - 1.
|
|
264
260
|
```
|
|
265
261
|
|
|
266
|
-
|
|
267
|
-
`
|
|
268
|
-
`snapshot
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
Unlike `stream()`, `snapshot()` does not advance the originating
|
|
273
|
-
`ClientSession`. Its returned `session` is the handle's full `ClientSessionState`, including the
|
|
274
|
-
opaque `inbox` value, with `streamIndex` set to the exact line after the captured prefix. Persist
|
|
275
|
-
it as is to restore the conversation later.
|
|
262
|
+
Like `stream({ follow: false })`, the read fixes the stream's end when it opens,
|
|
263
|
+
and `snapshot.session.streamIndex` is the line a live reader continues from.
|
|
264
|
+
`snapshot()` always reads from line `0` and doesn't advance the originating
|
|
265
|
+
`ClientSession`; use a bounded stream when you need only the unread suffix.
|
|
266
|
+
The returned `session` is the handle's full `ClientSessionState`, including the
|
|
267
|
+
opaque `inbox` value. Save it as is to restore the conversation later.
|
|
276
268
|
|
|
277
269
|
## Follow a subagent
|
|
278
270
|
|
|
279
|
-
A delegated subagent reports
|
|
271
|
+
A delegated subagent reports progress on its own child session. The parent stream announces each one with `child.opened`, whether a subagent tool or a [workflow tool](/docs/tools/workflows#delegate-work-ctxagent)'s `ctx.agent` opened it. Pass the event to `agent()` on the parent's handle to get the child's handle, then follow it with `stream()`:
|
|
280
272
|
|
|
281
273
|
```ts
|
|
282
274
|
import { endsTurn } from "eve/client";
|
|
@@ -294,18 +286,18 @@ if (opened?.type === "child.opened") {
|
|
|
294
286
|
}
|
|
295
287
|
```
|
|
296
288
|
|
|
297
|
-
Pass the received
|
|
289
|
+
Pass the event as you received it, including its position, because the parent's server checks that line before it returns child history. Cached events and their `stream` strings grant no access to another session or destination.
|
|
298
290
|
|
|
299
291
|
- Local children are read only after verifying the recorded relationship on the same deployment.
|
|
300
292
|
- Remote children use the parent deployment's proxy and the remote agent's authored `auth` and `headers`. The browser never needs the remote URL or its credentials. Foreign redirects are not followed.
|
|
301
293
|
|
|
302
|
-
To read a deeper child, pass its
|
|
294
|
+
To read a deeper child, pass its `child.opened` event to `child.agent(opened)`. Each hop verifies its own relationship, including through remote proxies, and fails instead of attaching by ID when the relationship is unsupported or unavailable. Paths are limited to eight hops.
|
|
303
295
|
|
|
304
|
-
The child has its own cursor, starting at `0`, and reading it never advances the parent's `streamIndex`. Pass `startIndex` to resume, `follow: false` for a bounded read, and `signal` to detach. A child
|
|
296
|
+
The child has its own cursor, starting at `0`, and reading it never advances the parent's `streamIndex`. Pass `startIndex` to resume, `follow: false` for a bounded read, and `signal` to detach. A child waits for more input after it answers. To read only the current turn, stop at the turn's end with `endsTurn`. A remote child on an earlier agent protocol still returns its result, but its descendant reader reports unsupported history.
|
|
305
297
|
|
|
306
298
|
## Observe nested traces without a framework
|
|
307
299
|
|
|
308
|
-
Use `SessionStore` when you
|
|
300
|
+
Use `SessionStore` when you want eve to track nested conversations for you instead of managing readers yourself:
|
|
309
301
|
|
|
310
302
|
```ts
|
|
311
303
|
import { SessionStore } from "eve/client";
|
|
@@ -333,17 +325,17 @@ try {
|
|
|
333
325
|
}
|
|
334
326
|
```
|
|
335
327
|
|
|
336
|
-
|
|
328
|
+
Creating a store doesn't start any reads. `observe()` starts observation and returns a cleanup function that is safe to call more than once. Observation is reference-counted, so it stops after every caller cleans up. Streaming the root also starts following children, and framework bindings start observation on mount. While observation is active, admitted children keep refreshing even after `followWhile` closes the root stream. No call waits for the whole tree to catch up.
|
|
337
329
|
|
|
338
|
-
`followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child
|
|
330
|
+
`followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child agents](../frontend/use-eve-agent#child-agents) for limits, states, and cursor semantics. Each child conversation shows the child's whole session. Use the parent's call results, not the child's messages, as the outcome of a call.
|
|
339
331
|
|
|
340
|
-
|
|
332
|
+
When the signed-in user or tenant changes, stop the old observation and create a new store. Token callbacks run again for each request without changing the observation key. For a cross-origin browser connection, expose `x-eve-observation-key` in the channel's CORS configuration alongside the stream version and tail headers.
|
|
341
333
|
|
|
342
|
-
|
|
334
|
+
To archive nested conversations, save their messages and each child's position in your own versioned format. `SessionView` is opaque and isn't an archive format. Children can advance while the root position stays the same. A failed observation keeps its last recorded data, so don't replace an existing archive with an empty failed read.
|
|
343
335
|
|
|
344
336
|
## Abort a request
|
|
345
337
|
|
|
346
|
-
Pass an `AbortSignal` to `send()` to abort submission, and to `stream()` or `result()` to abort a read. Aborting
|
|
338
|
+
Pass an `AbortSignal` to `send()` to abort submission, and to `stream()` or `result()` to abort a read. Aborting only detaches the client and never stops server-side work. To stop the active turn, call `session.cancel()` and watch for `turn.settled` with `outcome: "cancelled"`.
|
|
347
339
|
|
|
348
340
|
Arm the timeout before awaiting `send()` so it covers the POST as well as the stream:
|
|
349
341
|
|
|
@@ -362,10 +354,9 @@ for await (const event of response.stream({ signal: controller.signal })) {
|
|
|
362
354
|
clearTimeout(timeout);
|
|
363
355
|
```
|
|
364
356
|
|
|
365
|
-
An interrupted read
|
|
366
|
-
`response.result()` again without the aborted signal
|
|
367
|
-
|
|
368
|
-
resume observation.
|
|
357
|
+
An interrupted read doesn't consume the `Delivery`, and other concurrent readers keep running.
|
|
358
|
+
Call `response.stream()` or `response.result()` again without the aborted signal instead of
|
|
359
|
+
sending the message again.
|
|
369
360
|
|
|
370
361
|
## What to read next
|
|
371
362
|
|
package/docs/guides/decide.md
CHANGED
|
@@ -3,21 +3,14 @@ title: Automatic Model Selection
|
|
|
3
3
|
description: "Choose agent models automatically or ask typed questions in your tools and application code."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
inference begins. It uses the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions),
|
|
8
|
-
so the decider can be a Vercel AI Gateway model ID or a decision model from
|
|
9
|
-
an installed provider. Use `decide` from `eve/ai` to ask typed questions in
|
|
10
|
-
your own tools or application code.
|
|
6
|
+
`auto` from `eve/models` chooses an agent model from an allowlist before each turn's inference. `decide` from `eve/ai` asks typed questions in your own tools or application code. Both use the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions). The decider can be a Vercel AI Gateway model ID or a decision model from an installed provider.
|
|
11
7
|
|
|
12
8
|
The AI SDK decision model specification is experimental and can change in
|
|
13
9
|
patch releases.
|
|
14
10
|
|
|
15
11
|
## Choose from Gateway models
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
[Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK
|
|
19
|
-
model strings, it uses Vercel AI Gateway unless the application has configured a
|
|
20
|
-
different global default provider.
|
|
13
|
+
Omit `model` to decide with `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK model strings, it resolves through Vercel AI Gateway unless the application configures a different global default provider.
|
|
21
14
|
|
|
22
15
|
```ts title="agent/agent.ts"
|
|
23
16
|
import { defineAgent } from "eve";
|
|
@@ -33,17 +26,9 @@ export default defineAgent({
|
|
|
33
26
|
});
|
|
34
27
|
```
|
|
35
28
|
|
|
36
|
-
Configure Gateway authentication as
|
|
37
|
-
does not add a TypeSafe credential or transport layer. During `eve dev`, a
|
|
38
|
-
Gateway decider uses the same connection selected through `/login` as Gateway
|
|
39
|
-
language models. A configured AI SDK default provider still owns string model
|
|
40
|
-
resolution during development. The TUI footer displays `dynamic model` when the
|
|
41
|
-
agent uses `auto`, then adds the resolved model for the current turn, such as
|
|
42
|
-
`dynamic model · openai/gpt-6-luna`.
|
|
29
|
+
Configure Gateway authentication as for any other AI SDK model; there is no separate TypeSafe credential. During `eve dev`, a Gateway decider uses the connection selected through `/login`, unless a configured AI SDK default provider resolves string models. The TUI footer shows `dynamic model` and then the turn's resolved model, such as `dynamic model · openai/gpt-6-luna`.
|
|
43
30
|
|
|
44
|
-
Set `fallback` to keep the turn running when the decider is unavailable or
|
|
45
|
-
returns an error. The fallback can be a Gateway model ID, an AI SDK language
|
|
46
|
-
model instance, or an object with `model` and a `reasoning` override:
|
|
31
|
+
Set `fallback` to keep the turn running when the decider is unavailable or returns an error. The fallback can be a Gateway model ID, an AI SDK language model instance, or an object with `model` and a `reasoning` override:
|
|
47
32
|
|
|
48
33
|
```ts title="agent/agent.ts"
|
|
49
34
|
import { defineAgent } from "eve";
|
|
@@ -60,16 +45,11 @@ export default defineAgent({
|
|
|
60
45
|
});
|
|
61
46
|
```
|
|
62
47
|
|
|
63
|
-
The fallback applies only to decider failures. eve logs a warning with the
|
|
64
|
-
decider error and fallback identity when it switches models. Invalid prompts,
|
|
65
|
-
including requests without user text or with a latest message over the routing
|
|
66
|
-
limit, still fail before decider I/O. Cancelling the turn also aborts routing
|
|
67
|
-
instead of selecting the fallback.
|
|
48
|
+
The fallback applies only to decider failures. When eve switches, it logs a warning with the decider error and the fallback model. Invalid prompts and cancelled turns don't use the fallback; see [Runtime behavior](#runtime-behavior).
|
|
68
49
|
|
|
69
50
|
## Use a provider directly
|
|
70
51
|
|
|
71
|
-
Install the provider package
|
|
72
|
-
owns its credentials and settings.
|
|
52
|
+
Install the provider package and pass its decision model. The provider owns its credentials and settings.
|
|
73
53
|
|
|
74
54
|
```sh
|
|
75
55
|
pnpm add @ai-sdk/typesafe-ai
|
|
@@ -91,14 +71,11 @@ export default defineAgent({
|
|
|
91
71
|
});
|
|
92
72
|
```
|
|
93
73
|
|
|
94
|
-
Any provider that implements the AI SDK `Experimental_DecisionModel` contract
|
|
95
|
-
works here.
|
|
74
|
+
Any provider that implements the AI SDK `Experimental_DecisionModel` contract works.
|
|
96
75
|
|
|
97
76
|
## Route to provider models and set reasoning
|
|
98
77
|
|
|
99
|
-
|
|
100
|
-
Gateway model whose ID is the key. Use the object form when the selected model is
|
|
101
|
-
a provider instance, an alias, or needs a reasoning override.
|
|
78
|
+
The decider sees each option's key. A string value describes the Gateway model whose ID is the key. Use the object form for a provider instance, an alias, or a reasoning override.
|
|
102
79
|
|
|
103
80
|
```ts title="agent/agent.ts"
|
|
104
81
|
import { anthropic } from "@ai-sdk/anthropic";
|
|
@@ -120,22 +97,13 @@ export default defineAgent({
|
|
|
120
97
|
});
|
|
121
98
|
```
|
|
122
99
|
|
|
123
|
-
The decider sees option keys, descriptions, and recent text messages.
|
|
124
|
-
receives provider credentials or serialized language model instances. When it
|
|
125
|
-
selects `my_secret_model`, eve resolves the key back to the authored Anthropic
|
|
126
|
-
model.
|
|
100
|
+
The decider sees option keys, descriptions, and recent text messages, never provider credentials or model instances. When it selects `my_secret_model`, eve resolves the key back to the authored Anthropic model.
|
|
127
101
|
|
|
128
|
-
Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
|
|
129
|
-
`"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
|
|
130
|
-
agent's reasoning setting.
|
|
102
|
+
Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, and `"xhigh"`. Omit `reasoning` to inherit the agent's reasoning setting.
|
|
131
103
|
|
|
132
104
|
## Decide inside a tool
|
|
133
105
|
|
|
134
|
-
|
|
135
|
-
It defaults to `typesafe-ai/jev` and uses the same authentication as `auto`,
|
|
136
|
-
including the Gateway connection selected through `/login` during `eve dev`.
|
|
137
|
-
Pass `model` to use another decision model ID or a provider instance. A configured
|
|
138
|
-
AI SDK default provider takes precedence over the local Gateway connection.
|
|
106
|
+
`decide` asks choice, score, or boolean questions about the state you pass it. It defaults to `typesafe-ai/jev` with the same authentication as `auto`. Pass `model` to use another decision model ID or a provider instance.
|
|
139
107
|
|
|
140
108
|
```ts title="agent/tools/classify-request.ts"
|
|
141
109
|
import { decide } from "eve/ai";
|
|
@@ -165,33 +133,21 @@ export default defineTool({
|
|
|
165
133
|
});
|
|
166
134
|
```
|
|
167
135
|
|
|
168
|
-
The choice above is typed as `"billing" | "support"`. Each
|
|
169
|
-
its authored key in `result.answers`. Results also include normalized token usage in `usage`.
|
|
170
|
-
To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
|
|
136
|
+
The choice above is typed as `"billing" | "support"`. Each answer appears under its question's key in `result.answers`, and `usage` holds normalized token usage. To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
|
|
171
137
|
|
|
172
|
-
`decide` accepts `model`, `state`, `questions`, `maxRetries`, and `signal
|
|
173
|
-
Pass `signal: ctx.abortSignal` to cancel the request. Import `DecisionModel`, `DecisionState`,
|
|
174
|
-
`DecisionStatePart`, `DecisionInput`, `DecisionQuestion`, `DecisionAnswer`, `DecisionOptions`,
|
|
175
|
-
and `DecisionResult` from `eve/ai` to annotate reusable configs and handlers.
|
|
176
|
-
Model instances must implement decision model specification `v4`, the version AI SDK 7 supports;
|
|
177
|
-
a matching `provider`, `modelId`, and `specificationVersion` alone is not an implementation.
|
|
178
|
-
If the installed `ai` package does not export a decision API, `decide` throws an error naming the
|
|
179
|
-
missing export. Input and answer validation, retries, and provider errors follow AI SDK semantics.
|
|
138
|
+
`decide` accepts `model`, `state`, `questions`, `maxRetries`, and `signal`; pass `signal: ctx.abortSignal` to cancel with the tool call. Import `DecisionModel`, `DecisionState`, `DecisionStatePart`, `DecisionInput`, `DecisionQuestion`, `DecisionAnswer`, `DecisionOptions`, and `DecisionResult` from `eve/ai` to type reusable configs and handlers.
|
|
180
139
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
and
|
|
140
|
+
A model instance must implement decision model specification `v4`, the version AI SDK 7 supports. A matching `provider`, `modelId`, and `specificationVersion` alone is not enough. If the installed `ai` package does not export a decision API, `decide` throws an error that names the missing export. Validation, retries, and provider errors follow AI SDK semantics.
|
|
141
|
+
|
|
142
|
+
`decide` also works outside a tool and doesn't need an active eve session.
|
|
184
143
|
|
|
185
144
|
## Judge eval results
|
|
186
145
|
|
|
187
|
-
Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses
|
|
146
|
+
Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses `decide` and its default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
|
|
188
147
|
|
|
189
148
|
## Decide tool approvals
|
|
190
149
|
|
|
191
|
-
|
|
192
|
-
tool call can run automatically or needs human approval. It accepts the same
|
|
193
|
-
AI SDK decision model strings and provider instances described above and
|
|
194
|
-
defaults to `typesafe-ai/jev`:
|
|
150
|
+
`auto({ model? })` from `eve/tools/approval` lets a decision model decide whether a tool call runs automatically or needs human approval. It accepts the same decision model strings and provider instances and defaults to `typesafe-ai/jev`:
|
|
195
151
|
|
|
196
152
|
```ts title="agent/tools/deploy.ts"
|
|
197
153
|
import { defineTool } from "eve/tools";
|
|
@@ -206,8 +162,7 @@ export default defineTool({
|
|
|
206
162
|
});
|
|
207
163
|
```
|
|
208
164
|
|
|
209
|
-
The decision model reviews the tool name and input for dangerous effects. A
|
|
210
|
-
caution, failed review, or incomplete input requires human approval. See
|
|
165
|
+
The decision model reviews the tool name and input for dangerous effects. A caution, failed review, or incomplete input requires human approval. See
|
|
211
166
|
[Human-in-the-loop approvals](/docs/human-in-the-loop#approvals) for classifier
|
|
212
167
|
options and data handling, and the
|
|
213
168
|
[Auto-approve tool calls with Jev](https://vercel.com/kb/guide/auto-approve-tool-calls-eve-jev)
|
|
@@ -215,18 +170,8 @@ guide for an end-to-end walkthrough.
|
|
|
215
170
|
|
|
216
171
|
## Runtime behavior
|
|
217
172
|
|
|
218
|
-
`auto` decides before the first model call
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
The decider receives up to eight recent user and assistant text messages,
|
|
225
|
-
capped at 16,000 characters. Requests without user text and latest messages over
|
|
226
|
-
the limit fail before provider I/O.
|
|
227
|
-
|
|
228
|
-
Decision validation, retries, provider errors, and model resolution follow AI
|
|
229
|
-
SDK semantics. Without `fallback`, a decider error fails the turn. With
|
|
230
|
-
`fallback`, eve uses and retains that model for the rest of the turn. Cancelling
|
|
231
|
-
the active turn aborts decision and prevents a routed or fallback choice from
|
|
232
|
-
being retained.
|
|
173
|
+
`auto` decides once per turn, before the first model call. The choice holds for the turn's later model calls, including in a fresh process. A new turn makes a new choice, and child sessions route from their own prompts.
|
|
174
|
+
|
|
175
|
+
The decider receives up to eight recent user and assistant text messages, capped at 16,000 characters. A request without user text, or with a latest message over the limit, fails before provider I/O.
|
|
176
|
+
|
|
177
|
+
Without `fallback`, a decider error fails the turn; with it, eve uses the fallback model for the rest of the turn. Cancelling the turn aborts the decision and keeps no routed or fallback choice. Validation, retries, provider errors, and model resolution follow AI SDK semantics.
|
|
@@ -1,40 +1,51 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Overview"
|
|
3
|
-
description: "
|
|
3
|
+
description: "How an eve agent runs in production, and the backends you choose on Vercel or your own infrastructure."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Deploy eve to Vercel or run it as a Node service on your own infrastructure.
|
|
6
|
+
Deploy eve to Vercel or run it as a Node service on your own infrastructure. Both targets run on the open-source [Workflow SDK](https://workflow-sdk.dev/), so conversations, approvals, and subagent work survive restarts and long waits. The agent directory stays the same on every target.
|
|
7
7
|
|
|
8
|
-
## Choose a deployment
|
|
8
|
+
## Choose a deployment target
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
| Target | Build output | Choose it when |
|
|
11
|
+
| ------------------------------ | ---------------------- | --------------------------------------------------------------- |
|
|
12
|
+
| [Vercel](./vercel) | `.vercel/output` | You want Vercel to operate the runtime services |
|
|
13
|
+
| [Self-hosting](./self-hosting) | `.output/` Node server | You run Node services on your own servers or container platform |
|
|
11
14
|
|
|
12
|
-
|
|
13
|
-
| ------------------------------ | ---------------------- | ------------------------------ | ---------------- | ----------------------------------------------------- |
|
|
14
|
-
| [Vercel](./vercel) | `.vercel/output` | Vercel Workflow | Vercel Sandbox | You want Vercel to operate the runtime services |
|
|
15
|
-
| [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker or custom | You operate your own Node or container infrastructure |
|
|
15
|
+
You can also deploy eve beside a Next.js, Nuxt, SvelteKit, or TanStack Start application that routes browser requests to the agent. See [Frontend integrations](../frontend/overview).
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
## Backends
|
|
18
|
+
|
|
19
|
+
The eve server hands storage, isolation, model access, scheduling, and tracing to backends. Each deployment target picks a default for every backend, so a new agent deploys without backend configuration.
|
|
20
|
+
|
|
21
|
+
| Backend | What it does | On Vercel | Self-hosted |
|
|
22
|
+
| ---------------- | ------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------- |
|
|
23
|
+
| Workflow world | Stores sessions, queues their work, and resumes them after restarts | Vercel Workflow | [Local, Postgres, or another world package](./workflow-worlds) |
|
|
24
|
+
| Sandbox provider | Runs the `bash`, `read_file`, and `write_file` tools | Vercel Sandbox | Docker by default, or another [provider](../../sandbox) |
|
|
25
|
+
| Model access | Sends model calls | AI Gateway via OIDC | AI Gateway API key or an AI SDK provider package |
|
|
26
|
+
| Schedules | Runs authored [schedules](../../schedules) | Vercel Cron | The schedule runner in `eve start` |
|
|
27
|
+
| Observability | Records traces of sessions, turns, and tool calls | [Agent Runs](../../observability/agent-runs) | [OpenTelemetry](../../observability/otel) |
|
|
28
|
+
|
|
29
|
+
Self-hosted defaults store workflow state on disk, and run sandboxes in Docker when Docker is available during the build. See [Self-host eve](./self-hosting) for the persistent storage and sandbox setup your host must provide.
|
|
18
30
|
|
|
19
31
|
## Prepare for production
|
|
20
32
|
|
|
21
|
-
Every production deployment
|
|
33
|
+
Every production deployment needs these steps:
|
|
22
34
|
|
|
23
35
|
1. Run `eve build` to compile the agent and create host output.
|
|
24
36
|
2. Provide a model credential and any secrets required by tools, connections, and route authentication.
|
|
25
37
|
3. Replace `placeholderAuth()` with a production route policy before accepting browser traffic.
|
|
26
|
-
4.
|
|
27
|
-
5. Verify the health route and complete a real agent turn.
|
|
38
|
+
4. Verify the health route and complete a real agent turn.
|
|
28
39
|
|
|
29
|
-
`eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the
|
|
40
|
+
`eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the eve server under `.output/`.
|
|
30
41
|
|
|
31
42
|
## Configure credentials
|
|
32
43
|
|
|
33
|
-
Keep credentials in your deployment environment or secret manager
|
|
44
|
+
Keep credentials in your deployment environment or secret manager, not in source or compiled artifacts.
|
|
34
45
|
|
|
35
46
|
Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
|
|
36
47
|
|
|
37
|
-
|
|
48
|
+
Route authentication is separate from model access. The default policy rejects browser traffic in production. See [Authentication](../auth-and-route-protection) for the available policies and secret requirements.
|
|
38
49
|
|
|
39
50
|
## Verify the deployment
|
|
40
51
|
|
|
@@ -54,8 +65,6 @@ Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if a Vercel deployment uses
|
|
|
54
65
|
|
|
55
66
|
## Continue with a platform guide
|
|
56
67
|
|
|
57
|
-
Follow the guide for your deployment platform or application topology:
|
|
58
|
-
|
|
59
68
|
- [Deploy to Vercel](./vercel): use Vercel Build Output, Workflow, Sandbox, Cron, and observability
|
|
60
|
-
- [Self-host eve](./self-hosting): run the
|
|
69
|
+
- [Self-host eve](./self-hosting): run the eve server on Node with backends you choose
|
|
61
70
|
- [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, SvelteKit, or TanStack Start
|