eve 0.90.0 → 0.91.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- package/docs/tools/tasks-upgrade.md +0 -218
package/docs/agent-config.md
CHANGED
|
@@ -3,7 +3,7 @@ title: "Agent Configuration"
|
|
|
3
3
|
description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
An
|
|
6
|
+
An agent's optional `agent.ts` calls `defineAgent` (from `eve`) to configure the model and other runtime behavior. The root agent's file lives at `agent/agent.ts`, or in the app root with a [flat layout](./reference/agent-files#flat-layout). Declared [subagents](./subagents) have their own `agent.ts` and accept the same configuration.
|
|
7
7
|
|
|
8
8
|
## Set the model
|
|
9
9
|
|
|
@@ -17,18 +17,17 @@ export default defineAgent({
|
|
|
17
17
|
});
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
For a static AI Gateway model ID,
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
For a static AI Gateway model ID, make the same change with
|
|
21
|
+
`eve set model anthropic/claude-opus-5.5` from the project root or
|
|
22
|
+
`/model anthropic/claude-opus-5.5` in the local dev TUI.
|
|
23
23
|
|
|
24
|
-
|
|
25
|
-
When `agent.ts` is present, `model` is required.
|
|
24
|
+
Omit the root `agent.ts` to use `openai/gpt-6-luna-fast` with `reasoning: "high"`. When `agent.ts` is present, `model` is required.
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
Every local `agent.ts`, root or subagent, must export the value `defineAgent` returns, and so must a dynamic subagent resolver that selects a local agent. The build rejects a plain object with `Export defineAgent({...}) from "<path>".`
|
|
28
27
|
|
|
29
|
-
A
|
|
28
|
+
A gateway model ID string routes through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). To call a provider directly and configure the model in code, pass a model instance. eve types it as `EveLanguageModel`, exported from `eve` and `eve/models`, and every AI SDK language model satisfies it.
|
|
30
29
|
|
|
31
|
-
|
|
30
|
+
With a static Gateway model, `agent.ts` needs no code at runtime. A dynamic model or a model instance keeps `agent.ts` loaded at runtime, because eve resolves it while the agent runs. See [Authored module lifecycle](./reference/typescript-api#authored-module-lifecycle).
|
|
32
31
|
|
|
33
32
|
Use eve's helpers for direct OpenAI or Anthropic access without installing another provider package:
|
|
34
33
|
|
|
@@ -41,42 +40,34 @@ export default defineAgent({
|
|
|
41
40
|
});
|
|
42
41
|
```
|
|
43
42
|
|
|
44
|
-
`openai()` from `eve/models/openai` defaults to `gpt-6-luna-fast`. Both helpers accept an optional native provider model ID and
|
|
43
|
+
`openai()` from `eve/models/openai` defaults to `gpt-6-luna-fast`. Both helpers accept an optional native provider model ID and read `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. In local development they can also use credentials saved through `/login`; deployments need the API key in the server environment.
|
|
45
44
|
|
|
46
|
-
For a local ChatGPT subscription, use `chatgpt()` from `eve/models/openai` and sign in with `/login`. It defaults to `gpt-6-luna-fast` and
|
|
45
|
+
For a local ChatGPT subscription, use `chatgpt()` from `eve/models/openai` and sign in with `/login`. It defaults to `gpt-6-luna-fast` and can't run in a deployment.
|
|
47
46
|
|
|
48
|
-
`/login` can switch a static Gateway string to an eve helper and manage its import
|
|
47
|
+
`/login` can switch a static Gateway string to an eve helper and manage its import, and `/model` changes the selected model and settings immediately. Edit custom provider SDK calls and dynamic expressions by hand. For provider-specific configuration, install an AI SDK provider package and pass its language model.
|
|
49
48
|
|
|
50
49
|
Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct model instance.
|
|
51
50
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
`providerOptions.anthropic.metadata.userId
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
AI Gateway also uses this ID for
|
|
73
|
-
[session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity),
|
|
74
|
-
which tries the provider that served the session's previous call first, among
|
|
75
|
-
the providers your routing settings allow, so that provider can read the prompt
|
|
76
|
-
from its cache. The conversation
|
|
77
|
-
appears as one session in the AI Gateway logs Sessions view. Affinity can move
|
|
78
|
-
the pinned provider ahead of your `order`. To keep `order` exactly, set
|
|
79
|
-
`sessionAffinity: false`:
|
|
51
|
+
eve fills some provider options by default. A value you set at the same path
|
|
52
|
+
wins and is sent unchanged.
|
|
53
|
+
|
|
54
|
+
| Option | Calls | Default value |
|
|
55
|
+
| -------------------------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
56
|
+
| `providerOptions.openai.safetyIdentifier`, `providerOptions.anthropic.metadata.userId` | OpenAI and Anthropic model and compaction calls | SHA-256 fingerprint of the turn's [`auth.current`](./guides/auth-and-route-protection#what-reaches-ctxsessionauth) authenticator, issuer, type, id, and subject. Unset when `auth.current` is `null`. |
|
|
57
|
+
| `providerOptions.gateway.sessionId` | AI Gateway calls | The Agent Runs `gen_ai.conversation.id`, shared by every turn, delegated subagent, and compaction call in the conversation. |
|
|
58
|
+
| `providerOptions.openai.promptCacheKey` | Direct OpenAI and `chatgpt()` calls | SHA-256 hash of the session ID, unique per subagent session. |
|
|
59
|
+
|
|
60
|
+
The safety identifier never contains the caller's raw identity fields or attributes. It
|
|
61
|
+
follows the current caller when a later turn changes users. AI Gateway hashes
|
|
62
|
+
session IDs longer than 256 characters.
|
|
63
|
+
|
|
64
|
+
The Gateway session ID groups the conversation's generations into one session in
|
|
65
|
+
the AI Gateway logs Sessions view. It also drives
|
|
66
|
+
[session affinity](https://vercel.com/docs/ai-gateway/models-and-providers/session-affinity).
|
|
67
|
+
With affinity, AI Gateway first tries the provider that served the previous
|
|
68
|
+
call, so that provider can read the prompt from its cache. Affinity chooses only among the
|
|
69
|
+
providers your routing allows, but it can move one ahead of your `order`. To keep
|
|
70
|
+
`order` exactly, set `sessionAffinity: false`:
|
|
80
71
|
|
|
81
72
|
```ts title="agent/agent.ts"
|
|
82
73
|
import { defineAgent } from "eve";
|
|
@@ -91,20 +82,12 @@ export default defineAgent({
|
|
|
91
82
|
});
|
|
92
83
|
```
|
|
93
84
|
|
|
94
|
-
For direct OpenAI and `chatgpt()` model calls, eve sets
|
|
95
|
-
`providerOptions.openai.promptCacheKey` to a SHA-256 hash of the session ID,
|
|
96
|
-
which helps OpenAI route a session's calls to the cache that holds its prompt
|
|
97
|
-
prefix. Each subagent session gets its own key. An authored
|
|
98
|
-
`openai.promptCacheKey` takes precedence. `chatgpt()` calls also send the key
|
|
99
|
-
in the `session-id` header, which the Codex backend uses for cache routing.
|
|
100
|
-
Gateway-routed calls do not receive the option.
|
|
101
|
-
|
|
102
85
|
### Use a local model
|
|
103
86
|
|
|
104
|
-
To test against a model
|
|
105
|
-
[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers)
|
|
106
|
-
|
|
107
|
-
|
|
87
|
+
To test against a model on your own machine, use the AI SDK
|
|
88
|
+
[OpenAI-compatible provider](https://ai-sdk.dev/providers/openai-compatible-providers).
|
|
89
|
+
It works with any local server that implements the OpenAI Chat Completions API,
|
|
90
|
+
such as Ollama, LM Studio, llama.cpp, or vLLM. With
|
|
108
91
|
[Ollama](https://docs.ollama.com/api/openai-compatibility):
|
|
109
92
|
|
|
110
93
|
```bash
|
|
@@ -153,7 +136,7 @@ To select a model from the incoming prompt with an AI SDK decision model, use
|
|
|
153
136
|
[`auto` from `eve/models`](./guides/decide).
|
|
154
137
|
|
|
155
138
|
`model` also accepts `defineDynamic(fn)` from `eve/models` or `eve`. The function returns the
|
|
156
|
-
model
|
|
139
|
+
model, and a dynamic model has no compiled default.
|
|
157
140
|
|
|
158
141
|
```ts title="agent/agent.ts"
|
|
159
142
|
import { defineAgent } from "eve";
|
|
@@ -171,7 +154,7 @@ export default defineAgent({
|
|
|
171
154
|
The function returns a Gateway model ID, a model instance such as an AI SDK language model, or a selection object. See
|
|
172
155
|
[Dynamic capabilities](./guides/dynamic-capabilities) for the context and memo rules.
|
|
173
156
|
|
|
174
|
-
- **When it changes.** eve
|
|
157
|
+
- **When it changes.** eve runs the function before each ordinary model call. A memo keyed by
|
|
175
158
|
`ctx.turn?.id ?? null` keeps a choice for the turn; `ctx.session.id` keeps it until a deployment
|
|
176
159
|
change. Switching models can reduce prompt-cache reuse.
|
|
177
160
|
- **Failures stop the turn.** A thrown error or invalid selection fails the turn before the
|
|
@@ -179,10 +162,9 @@ The function returns a Gateway model ID, a model instance such as an AI SDK lang
|
|
|
179
162
|
- **Serialization.** Only memo results must be JSON. The function can return a live provider
|
|
180
163
|
instance built from those results. `ctx.model` is unavailable during model selection.
|
|
181
164
|
- **Selection object.** `{ model, reasoning?, modelContextWindowTokens?, modelOptions? }`.
|
|
182
|
-
|
|
183
|
-
`eve
|
|
184
|
-
|
|
185
|
-
newly published model, or rebuild. Dynamic agents cannot set sibling `modelContextWindowTokens` or
|
|
165
|
+
Omit `modelContextWindowTokens` to read it from the AI Gateway model catalog that `eve build` or
|
|
166
|
+
`eve dev` recorded, without a network request. A model that catalog doesn't list fails the turn. Set
|
|
167
|
+
`modelContextWindowTokens` for an unlisted, custom, or newly published model, or rebuild. Dynamic agents cannot set sibling `modelContextWindowTokens` or
|
|
186
168
|
`modelOptions` fields; return per-model values from the function.
|
|
187
169
|
|
|
188
170
|
The `session.started` runtime identity does not include a model ID for a dynamic agent. Each public
|
|
@@ -190,10 +172,9 @@ The `session.started` runtime identity does not include a model ID for a dynamic
|
|
|
190
172
|
|
|
191
173
|
## Reasoning effort
|
|
192
174
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
provider-agnostic option:
|
|
175
|
+
`reasoning` sets the model's reasoning effort through AI SDK's provider-agnostic
|
|
176
|
+
option. In an authored `agent.ts` with a static model, omit `reasoning` to use
|
|
177
|
+
the provider's default.
|
|
197
178
|
|
|
198
179
|
```ts title="agent/agent.ts"
|
|
199
180
|
export default defineAgent({
|
|
@@ -205,19 +186,18 @@ export default defineAgent({
|
|
|
205
186
|
Supported values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`,
|
|
206
187
|
`"medium"`, `"high"`, and `"xhigh"`. The selected model and provider determine
|
|
207
188
|
which levels are available and how they map to provider-native settings. Use
|
|
208
|
-
`modelOptions.providerOptions`
|
|
209
|
-
A dynamic model selection can return `reasoning`
|
|
210
|
-
|
|
211
|
-
`"provider-default"` explicitly uses the provider's default.
|
|
189
|
+
`modelOptions.providerOptions` for provider-specific reasoning controls.
|
|
190
|
+
A dynamic model selection can return `reasoning` to override the agent setting;
|
|
191
|
+
omit it to inherit the agent setting.
|
|
212
192
|
|
|
213
193
|
Run `eve set model --reasoning high` to update this field from the command line.
|
|
214
194
|
|
|
215
195
|
## Prompt caching
|
|
216
196
|
|
|
217
197
|
eve caches prompts automatically for AI Gateway models and for Anthropic models
|
|
218
|
-
it recognizes by provider or model id.
|
|
219
|
-
|
|
220
|
-
|
|
198
|
+
it recognizes by provider or model id. On a directly called model, set
|
|
199
|
+
`modelOptions.promptCache` to use a 1-hour cache. It also marks an unrecognized
|
|
200
|
+
model as Anthropic, such as a Bedrock application inference profile:
|
|
221
201
|
|
|
222
202
|
```ts title="agent/agent.ts"
|
|
223
203
|
import { bedrock } from "@ai-sdk/amazon-bedrock";
|
|
@@ -237,7 +217,7 @@ Gateway models; use `providerOptions.gateway.caching` instead.
|
|
|
237
217
|
|
|
238
218
|
## Compaction
|
|
239
219
|
|
|
240
|
-
Compaction summarizes older turns as
|
|
220
|
+
Compaction summarizes older turns as the conversation approaches the context window, and is on by default. The token count includes the fixed checkpoint prompt, so compaction starts before the conversation alone reaches the threshold. Lower `compaction.threshold`, a fraction from `0` to `1`, to compact sooner:
|
|
241
221
|
|
|
242
222
|
```ts title="agent/agent.ts"
|
|
243
223
|
export default defineAgent({
|
|
@@ -252,9 +232,8 @@ See [Default harness](./concepts/default-harness#compaction) for how the loop ap
|
|
|
252
232
|
|
|
253
233
|
## Runtime limits
|
|
254
234
|
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
session's usage and returns `true` when the limit is reached:
|
|
235
|
+
`limits` sets eve's runtime caps. `sessionUsage` receives the session's usage
|
|
236
|
+
and returns `true` when the session must stop starting model calls:
|
|
258
237
|
|
|
259
238
|
```ts title="agent/agent.ts"
|
|
260
239
|
export default defineAgent({
|
|
@@ -269,40 +248,40 @@ export default defineAgent({
|
|
|
269
248
|
});
|
|
270
249
|
```
|
|
271
250
|
|
|
272
|
-
`sessionTimeoutMs` sets how long
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
[
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
`
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
`
|
|
293
|
-
provider replays from its prompt cache on every step. `
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
`total` minus the session's
|
|
299
|
-
[total](./concepts/sessions-runs-and-streaming#replies-and-narration)
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
window:
|
|
251
|
+
`sessionTimeoutMs` sets how long any session, including a delegated session,
|
|
252
|
+
may sit idle before eve completes it. Omit it for 30 days, or set it to `false`
|
|
253
|
+
to disable the timeout. The idle window starts when the session is created. It
|
|
254
|
+
restarts each time a turn ends, including turns that clear or compact the
|
|
255
|
+
context or are cancelled. A session never expires while a turn is open, such as while its
|
|
256
|
+
[tasks](./tools/tasks) work or it waits for a person to answer. Process restarts
|
|
257
|
+
don't change the window.
|
|
258
|
+
|
|
259
|
+
When the window elapses, eve emits `session.ended` with `outcome: "completed"`
|
|
260
|
+
and releases the channel addresses, such as a Slack thread, that route messages
|
|
261
|
+
to the session. The next message at that address starts a new session. To carry the earlier conversation over, pass it as
|
|
262
|
+
[prior history](./channels/eve#start-from-prior-history). A session with
|
|
263
|
+
[zero retention](#run-data-retention) loses its stored payloads when it ends.
|
|
264
|
+
|
|
265
|
+
`sessionUsage` gets two `TokenUsage` records, a type exported from `eve`. `total` is everything the session has
|
|
266
|
+
spent, and `window` is what it spent since the last approved continuation. Each
|
|
267
|
+
record has these fields:
|
|
268
|
+
|
|
269
|
+
| Field | Meaning |
|
|
270
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
271
|
+
| `inputTokens` | All input, including cache reads and writes. |
|
|
272
|
+
| `cacheReadTokens` | History the provider replays from its prompt cache on every step. Subtract it from `inputTokens` to count only new input. |
|
|
273
|
+
| `cacheWriteTokens` | Input written to the prompt cache. |
|
|
274
|
+
| `outputTokens` | Generated output. |
|
|
275
|
+
| `costUsd` | Model token cost in US dollars that AI Gateway reports with each step. Excludes tool and infrastructure spend. Unset when no step reported a cost. |
|
|
276
|
+
|
|
277
|
+
`window` is `total` minus the session's
|
|
278
|
+
[total](./concepts/sessions-runs-and-streaming#replies-and-narration) when its
|
|
279
|
+
own budget prompt was last accepted. Before the first approval, it equals
|
|
280
|
+
`total`. Accepting a budget prompt that a subagent passed up starts the
|
|
281
|
+
subagent's window, not the parent's. The window survives redeploys and
|
|
282
|
+
replays.
|
|
283
|
+
|
|
284
|
+
Omit `sessionUsage` to stop at `40_000_000` new input tokens per window:
|
|
306
285
|
|
|
307
286
|
```ts
|
|
308
287
|
({ window }) => window.inputTokens - window.cacheReadTokens >= 40_000_000;
|
|
@@ -328,62 +307,65 @@ export default defineAgent({
|
|
|
328
307
|
});
|
|
329
308
|
```
|
|
330
309
|
|
|
331
|
-
Set `sessionUsage: false
|
|
332
|
-
|
|
333
|
-
the window has usage. The model call that crosses a limit
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
delegated runs without input proxying
|
|
356
|
-
call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
|
|
310
|
+
Set `sessionUsage: false`, or a callback that always returns `false`, to leave
|
|
311
|
+
sessions uncapped. eve calls a `sessionUsage` callback before each model call
|
|
312
|
+
once the window has usage. The model call that crosses a limit finishes, because
|
|
313
|
+
exact usage arrives after the call completes. Before the next model call, eve
|
|
314
|
+
pauses the turn (`turn.paused`) and sends a continuation prompt:
|
|
315
|
+
|
|
316
|
+
| Option | Result |
|
|
317
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
318
|
+
| **Continue** | Starts a new window and resumes the same turn. |
|
|
319
|
+
| **Stop** | Cancels the turn (`turn.settled` with `outcome: "cancelled"`), not an error. The session stays resumable, but because it is still over budget, the next message prompts again. |
|
|
320
|
+
|
|
321
|
+
Declining a delegated child's prompt cancels the root turn and the whole
|
|
322
|
+
delegation tree, so the parent never receives an error result it could retry.
|
|
323
|
+
|
|
324
|
+
A message that answers neither option waits behind the open prompt. It starts
|
|
325
|
+
no second prompt or turn. After **Continue**, the paused turn receives it
|
|
326
|
+
(`delivery.consumed`).
|
|
327
|
+
|
|
328
|
+
If an earlier deployment showed the continuation prompt, that turn has already
|
|
329
|
+
ended. A message that answers neither option waits behind the prompt and emits
|
|
330
|
+
no event until **Continue**. **Continue** starts a new turn that receives the
|
|
331
|
+
waiting message once.
|
|
332
|
+
|
|
333
|
+
Some sessions can't request input from a human, such as markdown schedules and
|
|
334
|
+
delegated runs without input proxying. They skip the prompt and fail the next
|
|
335
|
+
model call with `SESSION_USAGE_LIMIT_REACHED`. Its details carry the `total` and
|
|
357
336
|
`window` usage the check saw.
|
|
358
337
|
|
|
359
338
|
Each subagent session checks its own usage against its own `sessionUsage`, or
|
|
360
|
-
the root agent's when it authors none. A dynamic subagent
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
339
|
+
the root agent's when it authors none. A dynamic subagent always uses the root
|
|
340
|
+
agent's. Remote agents run under their own deployment's limits.
|
|
341
|
+
|
|
342
|
+
A child's usage, including its own subagents', also counts in the parent's
|
|
343
|
+
usage. Approving a continuation starts a new window without erasing `total`.
|
|
344
|
+
The parent counts delegated usage at these points:
|
|
345
|
+
|
|
346
|
+
| Delegated work | Counts against the parent |
|
|
347
|
+
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
348
|
+
| Agent task | With each reply. A turn with no reply, such as a cancelled one, counts with the next reply, or when the turn ends if no call waits. |
|
|
349
|
+
| `ctx.agent` session from any other `serve` workflow tool | The same way as an agent task. |
|
|
350
|
+
| `ctx.agent` session from an `execute` or `task` tool | When the tool finishes. |
|
|
351
|
+
| Remote agent | The same way as an agent task, cost included. |
|
|
352
|
+
|
|
353
|
+
Some delegated usage doesn't count against the parent:
|
|
354
|
+
|
|
355
|
+
- A `ctx.agent` turn still running when its workflow tool finishes or is cancelled.
|
|
356
|
+
- The `ctx.agent` usage of an `execute` tool whose parent turn is cancelled while it waits.
|
|
357
|
+
- What a cancelled agent task's own subagents spend after the task reports its cancelled turn.
|
|
358
|
+
|
|
359
|
+
A cancelled agent task ends and sends no further reply. Usage the cancelled run
|
|
360
|
+
reported up to that point still counts against the parent when its usage report
|
|
361
|
+
or final outcome arrives.
|
|
380
362
|
|
|
381
363
|
## Workflow world
|
|
382
364
|
|
|
383
|
-
|
|
384
|
-
Vercel
|
|
385
|
-
|
|
386
|
-
root `agent.ts`:
|
|
365
|
+
The Workflow world is the backend that stores and runs sessions, so they survive restarts and redeploys. Omit
|
|
366
|
+
`experimental.workflow.world` to use Vercel Workflow on Vercel and the SDK's
|
|
367
|
+
local world in local development or `eve start`. Self-hosted deployments can
|
|
368
|
+
select a world package in the root `agent.ts`:
|
|
387
369
|
|
|
388
370
|
```ts title="agent/agent.ts"
|
|
389
371
|
import { defineAgent } from "eve";
|
|
@@ -398,27 +380,26 @@ export default defineAgent({
|
|
|
398
380
|
});
|
|
399
381
|
```
|
|
400
382
|
|
|
401
|
-
Install
|
|
402
|
-
`createWorld()` function.
|
|
403
|
-
|
|
383
|
+
Install the package in your app; it must export a default factory or a
|
|
384
|
+
`createWorld()` function. Install a version built against the same
|
|
385
|
+
`@workflow/*` major version as your eve release, currently `5.x`:
|
|
404
386
|
|
|
405
387
|
```bash
|
|
406
|
-
pnpm add @workflow/world-postgres
|
|
388
|
+
pnpm add @workflow/world-postgres
|
|
407
389
|
```
|
|
408
390
|
|
|
409
|
-
|
|
410
|
-
|
|
391
|
+
eve fails at startup, naming the version to install, when the world targets a
|
|
392
|
+
different major version.
|
|
411
393
|
|
|
412
|
-
Put credentials
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
394
|
+
Put credentials, such as the Postgres connection string, and host-specific
|
|
395
|
+
options in the environment variables the world package reads, not in
|
|
396
|
+
`agent.ts`. If the package must stay external in hosted output, list it in
|
|
397
|
+
`build.externalDependencies`. See [Workflow worlds](./guides/deployment/workflow-worlds)
|
|
398
|
+
to choose a world and set up the Postgres world's database.
|
|
417
399
|
|
|
418
400
|
## Workflow checkpoint batching
|
|
419
401
|
|
|
420
|
-
|
|
421
|
-
inline tool calls. You can experimentally let one Workflow step run several
|
|
402
|
+
eve saves a Workflow step after every model call and its inline tool calls. `experimental.workflow.modelCallsPerStep` lets one step run several
|
|
422
403
|
sequential model calls:
|
|
423
404
|
|
|
424
405
|
```ts title="agent/agent.ts"
|
|
@@ -434,44 +415,41 @@ export default defineAgent({
|
|
|
434
415
|
});
|
|
435
416
|
```
|
|
436
417
|
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
This option is experimental and may change or
|
|
450
|
-
disappear in any release. See [Execution model and
|
|
451
|
-
durability](./concepts/execution-model-and-durability#resuming-after-a-crash)
|
|
418
|
+
The value is a positive-integer maximum. Omit it for `1`. It applies
|
|
419
|
+
separately to each root agent or declared subagent. A higher value can reduce
|
|
420
|
+
save overhead in sequential tool loops, but more work runs again after a crash.
|
|
421
|
+
If the step is interrupted, its earlier model calls and inline tool calls can
|
|
422
|
+
run again, repeating provider costs, events, and side effects. Use stable
|
|
423
|
+
idempotency keys for non-idempotent tools.
|
|
424
|
+
|
|
425
|
+
A batch ends before eve waits for input, authorization, or other blocking work.
|
|
426
|
+
It can end below the maximum when the turn completes or steering arrives. Before assistant output begins, steering can interrupt pending model
|
|
427
|
+
generation; running tools finish before the batch yields. This option is
|
|
428
|
+
experimental and may change or disappear in any release. See [Execution model
|
|
429
|
+
and durability](./concepts/execution-model-and-durability#resuming-after-a-crash)
|
|
452
430
|
for the retry behavior.
|
|
453
431
|
|
|
454
432
|
## Run data retention
|
|
455
433
|
|
|
456
|
-
|
|
457
|
-
|
|
434
|
+
Run-data retention is how long the Workflow World keeps a session's run data.
|
|
435
|
+
Omit `experimental.workflow.retention` to derive it from the session's resolved
|
|
436
|
+
[OpenTelemetry trace policy](./observability/otel#configure-opentelemetry) when
|
|
437
|
+
the session starts:
|
|
458
438
|
|
|
459
439
|
- When the policy allows both inputs and outputs, eve uses the World's default
|
|
460
440
|
retention period.
|
|
461
441
|
- When the policy drops the trace or excludes either content direction, eve
|
|
462
|
-
requests deletion
|
|
463
|
-
|
|
442
|
+
requests deletion when the run ends (Workflow's `experimental_retention: 0`).
|
|
443
|
+
Workflow can't delete inputs and outputs separately.
|
|
464
444
|
|
|
465
445
|
Without a custom policy, public conversations and development sessions use the
|
|
466
|
-
World's default. Private and unknown-audience sessions outside development
|
|
467
|
-
`0`, even
|
|
468
|
-
|
|
469
|
-
policies do not change it.
|
|
446
|
+
World's default. Private and unknown-audience sessions outside development
|
|
447
|
+
request `0`, even with no OpenTelemetry destination installed. Destination
|
|
448
|
+
export filters and lifecycle-provider policies don't change the decision.
|
|
470
449
|
|
|
471
|
-
Set `experimental.workflow.retention`
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
keep run data for the World's default period regardless of the tracing policy:
|
|
450
|
+
Set `experimental.workflow.retention` to `0` to always request deletion, or to
|
|
451
|
+
`"default"` to always keep run data for the World's default period. This
|
|
452
|
+
override is experimental and has no compatibility promise:
|
|
475
453
|
|
|
476
454
|
```ts title="agent/agent.ts"
|
|
477
455
|
import { defineAgent } from "eve";
|
|
@@ -486,46 +464,45 @@ export default defineAgent({
|
|
|
486
464
|
});
|
|
487
465
|
```
|
|
488
466
|
|
|
489
|
-
The resolved value applies to every run
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
timeouts and [workflow tools](./tools/workflows).
|
|
467
|
+
The resolved value applies to every run of the session, including runs after a
|
|
468
|
+
redeploy. Session timeout and [workflow tool](./tools/workflows) runs keep the
|
|
469
|
+
World's default.
|
|
493
470
|
|
|
494
|
-
|
|
495
|
-
|
|
471
|
+
Retention applies per agent. A [subagent](./subagents) with its own session uses
|
|
472
|
+
its own explicit value or derives retention from its resolved trace decision,
|
|
496
473
|
including any inherited content ceiling. `experimental.workflow.world` is root-only.
|
|
497
474
|
|
|
498
475
|
At `0`, supporting Worlds delete run and step inputs, outputs, and errors;
|
|
499
476
|
event payloads; and stream contents when the run reaches a terminal state. The
|
|
500
477
|
data remains available while the session is active. Run, step, and event records
|
|
501
|
-
remain for the World's default period
|
|
502
|
-
step names, and attributes
|
|
503
|
-
session title.
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
The Workflow World enforces deletion
|
|
507
|
-
|
|
508
|
-
|
|
478
|
+
remain for the World's default period. These records include IDs, timestamps,
|
|
479
|
+
statuses, step names, and attributes, which can contain content such as eve's
|
|
480
|
+
session title. Local traces, exported telemetry, and data stored by tools, channels, or
|
|
481
|
+
model providers are not deleted.
|
|
482
|
+
|
|
483
|
+
The Workflow World enforces deletion. A World older than spec version 4 rejects
|
|
484
|
+
`0`, and a spec version 4 World without retention support keeps the data.
|
|
485
|
+
Confirm support with your World provider. See
|
|
509
486
|
[Workflow data retention](https://workflow-sdk.dev/docs/observability/retention).
|
|
510
487
|
|
|
511
488
|
> ⚠️ **At `0`, completed session transcripts become unreadable.** Deletion races reads of finished runs. Depending on the World, reading deleted session history returns either an empty stream or `410` with `code: "session_expired"`. Persist anything you need to keep from inside a tool, or set `retention: "default"` to preserve completed-session reads independently of tracing.
|
|
512
489
|
|
|
513
490
|
## Other defineAgent fields
|
|
514
491
|
|
|
515
|
-
`defineAgent`
|
|
492
|
+
All other `defineAgent` fields are optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).
|
|
516
493
|
|
|
517
|
-
| Field | Type | Default | Description
|
|
518
|
-
| -------------- | ------------------------------------- | ---------------- |
|
|
519
|
-
| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls.
|
|
520
|
-
| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings.
|
|
521
|
-
| `limits` | `AgentLimitsDefinition` | field-specific |
|
|
522
|
-
| `experimental` | `AgentExperimentalDefinition` | unset | Unstable opt-ins
|
|
523
|
-
| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages
|
|
524
|
-
| `tool` | `boolean \| "deferred"` | `true` | Exposes this agent to its parent model as a tool. `"deferred"`
|
|
494
|
+
| Field | Type | Default | Description |
|
|
495
|
+
| -------------- | ------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
496
|
+
| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
|
|
497
|
+
| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call, and [`promptCache`](#prompt-caching) settings. |
|
|
498
|
+
| `limits` | `AgentLimitsDefinition` | field-specific | eve's [runtime limits](#runtime-limits). |
|
|
499
|
+
| `experimental` | `AgentExperimentalDefinition` | unset | Unstable opt-ins: [`workflow.world`](#workflow-world), [`workflow.modelCallsPerStep`](#workflow-checkpoint-batching), and [`workflow.retention`](#run-data-retention). |
|
|
500
|
+
| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages unbundled and includes them in the hosted output. |
|
|
501
|
+
| `tool` | `boolean \| "deferred"` | `true` | Exposes this agent to its parent model as a tool. `"deferred"` hides it from the tool list until the model finds it with `eve__search` and calls it with `eve__tool`. On the root agent, controls the built-in `agent` tool. With `false`, authored workflow tools can still call a subagent through `ctx.agent()`. |
|
|
525
502
|
|
|
526
|
-
`externalDependencies`
|
|
503
|
+
`externalDependencies` only controls packaging; it doesn't authorize, configure, or review any third-party service those packages call.
|
|
527
504
|
|
|
528
|
-
During `eve dev`,
|
|
505
|
+
During `eve dev`, packages listed in `externalDependencies` use normal Node.js resolution instead of being bundled, so restart the dev server after replacing one.
|
|
529
506
|
|
|
530
507
|
## Where adjacent settings live
|
|
531
508
|
|