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
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Operate a Self-Hosted Agent"
|
|
3
|
+
description: "Upgrade, scale, and troubleshoot an eve agent that runs on your own infrastructure."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use this guide after your agent runs with [`eve start`](./self-hosting). It covers upgrades, replicas, schedules, workspace members, run data, and common failures.
|
|
7
|
+
|
|
8
|
+
## Upgrade a self-hosted agent
|
|
9
|
+
|
|
10
|
+
A self-hosted Workflow world serves one eve version at a time. Deploying a new build of your agent on the same eve release keeps existing sessions running. Upgrading eve strands sessions started by the previous version: their recorded history remains readable, but they cannot resume. See [Recover a stranded session](#recover-a-stranded-session) for how a new channel message starts a replacement.
|
|
11
|
+
|
|
12
|
+
To deploy a new build:
|
|
13
|
+
|
|
14
|
+
1. Stop the processes running the previous build.
|
|
15
|
+
2. With the Postgres world, run `bootstrap` if the build upgrades `@workflow/world-postgres`; see [Use the Postgres world](./workflow-worlds#use-the-postgres-world).
|
|
16
|
+
3. Start the new build with `eve start`.
|
|
17
|
+
|
|
18
|
+
When the eve version is unchanged, the new build resumes runs that were active when the previous processes stopped.
|
|
19
|
+
|
|
20
|
+
### Recover a stranded session
|
|
21
|
+
|
|
22
|
+
A session is **stranded** when another eve version built its workflow run, so the current deployment cannot replay it. Its history stays readable, but it cannot process new work. A new message to its channel address starts a replacement session, and `ctx.session.predecessor` names the stranded one. See [Stranded sessions](../../concepts/execution-model-and-durability#stranded-sessions) for behavior in each world and how the replacement reads the earlier conversation.
|
|
23
|
+
|
|
24
|
+
## Run replicas
|
|
25
|
+
|
|
26
|
+
Use the [Postgres world](./workflow-worlds#use-the-postgres-world) to serve an agent from several `eve start` processes. Every process connected to the database runs queued work, so any replica can continue any session. The local world serves one process.
|
|
27
|
+
|
|
28
|
+
Configure each replica the same way, with two differences:
|
|
29
|
+
|
|
30
|
+
- Run schedules on one replica only; see [Run schedules](#run-schedules).
|
|
31
|
+
- Give every replica access to the same sandboxes. A session records its sandbox, and the next replica to run the session resumes it. A Docker sandbox lives on the Docker daemon of the host that created it. A replica that can't find it starts a fresh sandbox without the earlier files if its own daemon has the build's sandbox image, and fails with `SandboxTemplateNotProvisionedError` otherwise. For replicas on several hosts, use a provider every replica can reach, such as [Vercel Sandbox](../../sandbox/vercel) or a [custom provider](../../sandbox/custom-providers).
|
|
32
|
+
|
|
33
|
+
## Run schedules
|
|
34
|
+
|
|
35
|
+
`eve start` runs every authored schedule. On a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
|
|
36
|
+
|
|
37
|
+
When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
|
|
38
|
+
|
|
39
|
+
## Run workspace members
|
|
40
|
+
|
|
41
|
+
An [agent workspace](../../concepts/project-structure#several-root-agents) needs neither Vercel nor a frontend at runtime. Build each member from its own directory, because a root `eve build` produces a Vercel workspace deployment.
|
|
42
|
+
|
|
43
|
+
For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
(cd agents/support && npx eve build)
|
|
47
|
+
(cd agents/research && npx eve build)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Start each built agent in a separate terminal, or configure these commands in your process manager:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
(cd agents/support && npx eve start --host 127.0.0.1 --port 3001)
|
|
54
|
+
(cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
This Caddy configuration gives each agent its own origin and forwards all paths unchanged. Point the hostnames at your server and run Caddy on the same machine:
|
|
58
|
+
|
|
59
|
+
```text
|
|
60
|
+
support.example.com {
|
|
61
|
+
reverse_proxy 127.0.0.1:3001
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
research.example.com {
|
|
65
|
+
reverse_proxy 127.0.0.1:3002
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Apply the [authentication, Workflow world, and sandbox configuration](./self-hosting) to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory.
|
|
70
|
+
|
|
71
|
+
If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials, because the default transport requires Vercel. Remote agent callbacks must reach a public address. Outside `eve dev`, eve refuses callback hosts that are, or resolve to, loopback, private, link-local, or reserved addresses. So callbacks between services over a private network or `127.0.0.1` don't work. See [How remote dispatch and callbacks work](../remote-agents#how-remote-dispatch-and-callbacks-work) and [Set the public callback origin](./self-hosting#set-the-public-callback-origin).
|
|
72
|
+
|
|
73
|
+
### Add a peer frontend
|
|
74
|
+
|
|
75
|
+
A frontend under `apps/web/` is a separate service that runs with its framework commands, not `eve start`. A browser client can call an agent origin directly with `useEveAgent({ baseUrl: "https://support.example.com" })`. Configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy.
|
|
76
|
+
|
|
77
|
+
For path-based mounts, strip the public prefix before forwarding to the agent. Set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
|
|
78
|
+
|
|
79
|
+
To have Next.js start the built agent processes and provide the browser-facing proxy routes, use [`eve/next`](../frontend/nextjs#self-host). A self-hosted process manager ignores `eve/vercel` configuration.
|
|
80
|
+
|
|
81
|
+
## Manage run data
|
|
82
|
+
|
|
83
|
+
The Workflow world holds every session's history. Back it up with the rest of your application data:
|
|
84
|
+
|
|
85
|
+
- **Local world:** back up the `.eve/.workflow-data` directory.
|
|
86
|
+
- **Postgres world:** back up the database. The Postgres world keeps the records of finished runs until you delete them.
|
|
87
|
+
|
|
88
|
+
eve can ask the world to delete a run's inputs, outputs, and stream contents when the run ends. See [Run data retention](../../agent-config#run-data-retention) for the default policy and the override.
|
|
89
|
+
|
|
90
|
+
## Troubleshoot a self-hosted agent
|
|
91
|
+
|
|
92
|
+
| Symptom | Check | Next action |
|
|
93
|
+
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| Sandbox tools fail with `DefaultSandbox has no sandbox provider for this build` | Whether `eve build` could reach a Docker daemon, for example inside a Dockerfile `RUN` step | Rebuild where Docker is reachable, or [select a provider explicitly](./self-hosting#build-inside-a-container-image) |
|
|
95
|
+
| Workflow deliveries fail with HTTP 401 with the local world | Whether `WORKFLOW_LOCAL_BASE_URL` reaches a load balancer in front of several processes | Serve the agent from one process, or use the [Postgres world](./workflow-worlds#use-the-postgres-world) for replicas |
|
|
96
|
+
| Sign-in links or remote agent callbacks point at `localhost` | Whether `WORKFLOW_LOCAL_BASE_URL` is set | [Set the public callback origin](./self-hosting#set-the-public-callback-origin) |
|
|
97
|
+
| A session starts but never responds behind a proxy | With `WORKFLOW_LOCAL_BASE_URL` pointing at the proxy, whether the proxy forwards `/.well-known/workflow/` without rewriting the path | Forward both [proxy route prefixes](./self-hosting#configure-proxy-routes) |
|
|
98
|
+
| Requests return `409` with `code: "session_stranded"` after an upgrade | The eve version in the response | End the session, or send a new message to its channel address; see [Recover a stranded session](#recover-a-stranded-session) |
|
|
99
|
+
| Schedules run more than once | How many replicas run without `--no-schedules` | [Run schedules](#run-schedules) on one replica |
|
|
@@ -1,145 +1,128 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Self-Host eve"
|
|
3
|
-
description: "Run an eve agent as a Node service
|
|
3
|
+
description: "Run an eve agent as a Node service on your own infrastructure, and choose the Workflow world and sandbox it uses."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Self-host eve
|
|
6
|
+
Self-host eve by running the Node server that `eve build` produces on your own servers, container platform, or behind your own reverse proxy. The server runs every session as a durable workflow, so conversations, human approvals, and subagent work survive process restarts. eve backs that durability with a [Workflow world](./workflow-worlds) and runs shell and file tools in a [sandbox](../../sandbox). Both have self-hosted defaults, and you can replace either one without changing your agent's behavior.
|
|
7
7
|
|
|
8
|
-
##
|
|
8
|
+
## What a self-hosted deployment needs
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Every self-hosted deployment needs:
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
12
|
+
- A model credential and a production route policy; see [Configure model access and route auth](#configure-model-access-and-route-auth)
|
|
13
|
+
- Persistent storage for the Workflow world; see [Choose a Workflow world](#choose-a-workflow-world)
|
|
14
|
+
- A Node process serving the build; see [Build and start the server](#build-and-start-the-server)
|
|
15
|
+
- A reverse proxy that forwards both runtime route prefixes; see [Configure proxy routes](#configure-proxy-routes)
|
|
16
16
|
|
|
17
|
-
The
|
|
18
|
-
|
|
19
|
-
Run this process under the same process manager or container platform you use for other Node web services. Configure Transport Layer Security (TLS), scaling, restarts, and log collection in that platform.
|
|
17
|
+
The sections below follow that order and end by verifying a real turn. Configure [additional features](#configure-additional-features) as your agent needs them.
|
|
20
18
|
|
|
21
19
|
## Configure model access and route auth
|
|
22
20
|
|
|
23
|
-
Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway
|
|
24
|
-
|
|
25
|
-
Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Authentication](../auth-and-route-protection).
|
|
21
|
+
Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models), pass its model object in `agent.ts`, and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
Outside Vercel, use an authenticator your host can validate as the production route policy, such as Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier, rather than `vercelOidc()` alone. See [Authentication](../auth-and-route-protection).
|
|
28
24
|
|
|
29
|
-
|
|
25
|
+
## Choose a Workflow world
|
|
30
26
|
|
|
31
|
-
|
|
27
|
+
For one process, use the default local world. It needs no configuration and stores session state under `.eve/.workflow-data`; mount that directory on persistent storage so sessions survive process and container replacement. For replicas or hosts without persistent disk, configure the [Postgres world](./workflow-worlds#use-the-postgres-world). To use your own world implementation, see [Use another world](./workflow-worlds#use-another-world).
|
|
32
28
|
|
|
33
|
-
|
|
29
|
+
See [Workflow worlds](./workflow-worlds) to compare and configure the available worlds.
|
|
34
30
|
|
|
35
|
-
|
|
31
|
+
## Build and start the server
|
|
36
32
|
|
|
37
|
-
|
|
38
|
-
import { defineAgent } from "eve";
|
|
33
|
+
If your agent uses sandbox tools or file attachments, make Docker available during the build and at runtime, or [select a sandbox provider explicitly](#run-the-sandbox). For Dockerfile builds, see [Build inside a container image](#build-inside-a-container-image) below.
|
|
39
34
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
workflow: {
|
|
44
|
-
world: "@acme/eve-workflow-world",
|
|
45
|
-
},
|
|
46
|
-
},
|
|
47
|
-
});
|
|
35
|
+
```bash
|
|
36
|
+
eve build
|
|
37
|
+
PORT=3000 eve start --host 0.0.0.0
|
|
48
38
|
```
|
|
49
39
|
|
|
50
|
-
The
|
|
51
|
-
|
|
52
|
-
See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
|
|
53
|
-
|
|
54
|
-
## Recover a stranded session
|
|
40
|
+
The build writes the eve server under `.output/`. `eve start` serves that output and accepts either `PORT` or the `--port` flag. To run the server from another directory, copy the app source, `.output/`, and installed dependencies together.
|
|
55
41
|
|
|
56
|
-
|
|
42
|
+
The output is a standard [Nitro](https://nitro.build) Node server. If you adapt it to a host or preset instead of running `eve start`, see [Run schedules](./self-hosted-operations#run-schedules).
|
|
57
43
|
|
|
58
|
-
|
|
44
|
+
Run the process under the same process manager or container platform you use for other Node web services, and configure Transport Layer Security (TLS), restarts, and log collection there.
|
|
59
45
|
|
|
60
|
-
|
|
46
|
+
### Build inside a container image
|
|
61
47
|
|
|
62
|
-
|
|
48
|
+
A `RUN eve build` step in a Dockerfile usually has no Docker daemon, so the build records no sandbox provider, even when the running container later mounts `/var/run/docker.sock`. Select `DockerSandbox.environment()` explicitly in that setup:
|
|
63
49
|
|
|
64
|
-
|
|
50
|
+
```typescript title="agent/sandbox.ts"
|
|
51
|
+
import { defineSandbox } from "eve/sandbox";
|
|
52
|
+
import { DockerSandbox } from "eve/sandbox/docker";
|
|
65
53
|
|
|
66
|
-
|
|
54
|
+
export const environment = DockerSandbox.environment();
|
|
55
|
+
export default defineSandbox(() => environment.open());
|
|
56
|
+
```
|
|
67
57
|
|
|
68
|
-
|
|
58
|
+
You can instead run `eve build` where Docker is reachable and copy the output into the image. See [Run the sandbox](#run-the-sandbox) for the other providers.
|
|
69
59
|
|
|
70
60
|
## Configure proxy routes
|
|
71
61
|
|
|
72
|
-
Forward both runtime route prefixes through your reverse proxy or ingress:
|
|
62
|
+
Forward both runtime route prefixes through your reverse proxy or ingress without rewriting their paths:
|
|
73
63
|
|
|
74
64
|
- `/eve/` serves health, sessions, streams, channels, tools, and subagents
|
|
75
65
|
- `/.well-known/workflow/` receives workflow callbacks
|
|
76
66
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
## Run workspace members
|
|
67
|
+
If the proxy forwards only `/eve/`, a session starts but the run stalls because its workflow callback can’t reach eve.
|
|
80
68
|
|
|
81
|
-
|
|
69
|
+
## Verify the service
|
|
82
70
|
|
|
83
|
-
|
|
71
|
+
After your proxy and authentication are active, check the health route:
|
|
84
72
|
|
|
85
73
|
```bash
|
|
86
|
-
|
|
87
|
-
(cd agents/research && npx eve build)
|
|
74
|
+
curl https://your_agent.example.com/eve/v1/health
|
|
88
75
|
```
|
|
89
76
|
|
|
90
|
-
|
|
77
|
+
Then connect the development TUI and complete a real turn:
|
|
91
78
|
|
|
92
79
|
```bash
|
|
93
|
-
|
|
94
|
-
(cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
|
|
80
|
+
eve remote connect --url https://your_agent.example.com
|
|
95
81
|
```
|
|
96
82
|
|
|
97
|
-
|
|
83
|
+
## Configure additional features
|
|
98
84
|
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
85
|
+
| Feature | Configuration |
|
|
86
|
+
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
87
|
+
| Sandbox tools, file attachments, and skill supporting files | [Run the sandbox](#run-the-sandbox) with Docker or another provider |
|
|
88
|
+
| [Schedules](../../schedules) | Keep schedules enabled on [one `eve start` process](./self-hosted-operations#run-schedules) |
|
|
89
|
+
| Slack, Microsoft Teams, and other [channels](../../channels/overview) | Expose `/eve/` over public HTTPS through your [proxy](#configure-proxy-routes) |
|
|
90
|
+
| Connection sign-in and [remote agents](../remote-agents) | Set a [public callback origin](#set-the-public-callback-origin) |
|
|
91
|
+
| Agents in a workspace that call each other | Configure a [workspace-peer transport](../../subagents#vercel-workspace-peers) |
|
|
92
|
+
| Traces | Configure an [OpenTelemetry](../../observability/otel) destination |
|
|
103
93
|
|
|
104
|
-
|
|
105
|
-
reverse_proxy 127.0.0.1:3002
|
|
106
|
-
}
|
|
107
|
-
```
|
|
94
|
+
## Run the sandbox
|
|
108
95
|
|
|
109
|
-
|
|
96
|
+
eve runs the sandbox in Docker when `eve build` can reach a Docker daemon, and records that choice in the build.
|
|
110
97
|
|
|
111
|
-
|
|
98
|
+
A session starts its sandbox when a tool, a file attachment, or a skill's supporting files need it, and early when a client [prewarms](../frontend/use-eve-agent#prewarming) the session. Sessions, approvals, subagents, schedules, and authored tools that don't call `ctx.getSandbox()` work without a sandbox. Without one, a file attachment reaches the model as a text note instead of a file.
|
|
112
99
|
|
|
113
|
-
|
|
100
|
+
To run sandboxes elsewhere, or when the build cannot reach Docker, select a provider in your sandbox module:
|
|
114
101
|
|
|
115
|
-
|
|
102
|
+
- `VercelSandbox.environment()` creates hosted [Vercel Sandbox](../../sandbox/vercel) sessions from any host. Outside Vercel and without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`.
|
|
103
|
+
- `DockerSandbox.environment()` from `eve/sandbox/docker` selects [Docker](../../sandbox/docker) regardless of what the build can reach.
|
|
104
|
+
- `defineSandboxProvider()` connects a [custom provider](../../sandbox/custom-providers), such as your own container, virtual machine, or isolation service.
|
|
116
105
|
|
|
117
|
-
|
|
106
|
+
See [Sandbox](../../sandbox) for provider configuration and selection order.
|
|
118
107
|
|
|
119
|
-
##
|
|
108
|
+
## Set the public callback origin
|
|
120
109
|
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
|
|
124
|
-
|
|
125
|
-
## Verify the service
|
|
126
|
-
|
|
127
|
-
Check the health route after your proxy and authentication configuration are active:
|
|
110
|
+
Connection sign-in links and the callback URLs a parent passes to [remote agents](../remote-agents) start from the server's own address, which is `http://localhost:<port>` outside Vercel. Set `WORKFLOW_LOCAL_BASE_URL` to the agent's public origin, such as `https://support.example.com`, when your agent uses either feature:
|
|
128
111
|
|
|
129
112
|
```bash
|
|
130
|
-
|
|
113
|
+
WORKFLOW_LOCAL_BASE_URL=https://support.example.com eve start --host 0.0.0.0
|
|
131
114
|
```
|
|
132
115
|
|
|
133
|
-
|
|
116
|
+
With the local world, queued work is also delivered to that origin, so those deliveries pass through your proxy. Forward both [proxy route prefixes](#configure-proxy-routes), and keep a single process behind that origin; see [Use the local world](./workflow-worlds#use-the-local-world). The Postgres world delivers queued work inside each process, so its deliveries don't use this origin.
|
|
134
117
|
|
|
135
|
-
|
|
136
|
-
eve remote connect --url https://your_agent.example.com
|
|
137
|
-
```
|
|
118
|
+
For an agent mounted under a path prefix, also set `EVE_PUBLIC_ROUTE_PREFIX`; see [Run workspace members](./self-hosted-operations#run-workspace-members).
|
|
138
119
|
|
|
139
120
|
## Continue configuring production
|
|
140
121
|
|
|
141
|
-
Use these guides to secure and observe the deployed agent:
|
|
122
|
+
Use these guides to scale, secure, and observe the deployed agent:
|
|
142
123
|
|
|
124
|
+
- [Workflow worlds](./workflow-worlds): configure the local, Postgres, or another world
|
|
125
|
+
- [Operate a self-hosted agent](./self-hosted-operations): upgrade builds, run replicas and schedules, and troubleshoot
|
|
143
126
|
- [Authentication](../auth-and-route-protection): configure the host’s route policy
|
|
144
127
|
- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
|
|
145
128
|
- [Sandbox](../../sandbox): select and secure a sandbox provider
|
|
@@ -3,33 +3,33 @@ title: "Deploy to Vercel"
|
|
|
3
3
|
description: "Deploy an eve agent with Vercel Workflow, Sandbox, Cron, and project credentials."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
On Vercel, eve builds to Vercel Build Output, and Vercel runs the agent’s web service, workflows, sandboxes, schedules, and observability.
|
|
7
7
|
|
|
8
8
|
## Prepare the Vercel project
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Link the project from its root, or from the workspace root for an eve agent workspace:
|
|
11
11
|
|
|
12
12
|
```bash
|
|
13
13
|
eve link
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
`eve link` links an existing project or creates one, then pulls its environment variables. For non-interactive use, name the project:
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
eve link --project your_project_name --non-interactive
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
Add `--team` when the account has access to more than one team.
|
|
23
23
|
|
|
24
24
|
## Configure credentials and auth
|
|
25
25
|
|
|
26
|
-
A string model ID routes requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). The deployment authenticates through project OpenID Connect (OIDC), so
|
|
26
|
+
A string model ID routes requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). The deployment authenticates to it through project OpenID Connect (OIDC), so it needs no provider API key.
|
|
27
27
|
|
|
28
|
-
Add credentials for direct model providers, tools, and connections to the Vercel project environment.
|
|
28
|
+
Add credentials for direct model providers, tools, and connections to the Vercel project environment. Also add any signing keys or passwords your [route authentication policy](../auth-and-route-protection) requires. Replace `placeholderAuth()` before a browser sends a production request.
|
|
29
29
|
|
|
30
30
|
## Select the sandbox environment
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
On Vercel, the default sandbox environment selects Vercel Sandbox. To select it explicitly:
|
|
33
33
|
|
|
34
34
|
```typescript
|
|
35
35
|
import { defineSandbox } from "eve/sandbox";
|
|
@@ -39,25 +39,25 @@ export const environment = VercelSandbox.environment();
|
|
|
39
39
|
export default defineSandbox(() => environment.open());
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and
|
|
42
|
+
See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and sandbox lifetime.
|
|
43
43
|
|
|
44
44
|
<Callout type="info" title="Sandbox prewarming">
|
|
45
45
|
During a Vercel build, eve creates or reuses a snapshot-backed template when an environment uses
|
|
46
46
|
`VercelSandbox.environment({prepare})` or has seed files. A prewarm failure stops the deployment.
|
|
47
|
-
See
|
|
47
|
+
See [how long a sandbox lasts](../../sandbox#lifecycle).
|
|
48
48
|
</Callout>
|
|
49
49
|
|
|
50
50
|
## Deploy the agent
|
|
51
51
|
|
|
52
|
-
For a single-agent project without a frontend, use `eve build`. For an agent-only workspace, run it from the workspace root
|
|
52
|
+
For a single-agent project without a frontend, use `eve build`. For an agent-only workspace, run it from the workspace root. Each member gets a separately built service and an `/eve/<name>/v1/*` transport route, and all members deploy together in one Vercel project. See [Project Structure](../../concepts/project-structure) for workspace layout rules.
|
|
53
53
|
|
|
54
|
-
A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) and its Next.js build command.
|
|
54
|
+
A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) and its Next.js build command. To author the project's service graph in `vercel.ts`, use the configuration below instead.
|
|
55
55
|
|
|
56
56
|
### Compose agents with other Vercel services
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
`withEve` from `eve/vercel` adds eve agents to a Vercel service graph as peers of your other applications, with no frontend framework required. Unlike `eve/next`, it doesn't depend on a Next.js build. Both deploy the agent services together in one Vercel project.
|
|
59
59
|
|
|
60
|
-
For a standalone agent or workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend
|
|
60
|
+
For a standalone agent or workspace with a peer Next.js frontend under `apps/web/`, replace `vercel.json` with a root `vercel.ts`. The frontend keeps an ordinary Next.js config without `eve/next`:
|
|
61
61
|
|
|
62
62
|
```typescript title="vercel.ts"
|
|
63
63
|
import { withEve } from "eve/vercel";
|
|
@@ -79,15 +79,21 @@ export default await withEve({
|
|
|
79
79
|
});
|
|
80
80
|
```
|
|
81
81
|
|
|
82
|
-
|
|
82
|
+
`withEve` adds the root agent, or every direct workspace member, as an independently built service and returns a plain Vercel configuration. Named workspace agents mount at `/eve/<name>/v1/*`; a root agent mounts at `/eve/v1/*`. Vercel builds the frontend and each agent separately, so the frontend needs neither `withEve` in its framework configuration nor a script that builds the agents.
|
|
83
83
|
|
|
84
|
-
The Web Chat installer can generate this composition for a standalone agent or a selected workspace agent. Configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-
|
|
84
|
+
The Web Chat installer can generate this composition for a standalone agent or a selected workspace agent. Configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosted-operations#run-workspace-members).
|
|
85
85
|
|
|
86
|
-
Run Vercel CLI 59.16.0 or newer
|
|
86
|
+
Run `vercel dev --local` with Vercel CLI 59.16.0 or newer to start the whole service graph locally without linking a project. A linked directory also loads its development environment and settings. A generated Vercel Web Chat project exposes the scripts below. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Import that helper from `eve/experimental/workspace`; see [Vercel workspace peers](../../subagents#vercel-workspace-peers). The workspace layout and `eve/vercel` integration are not experimental.
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
| Script | Starts |
|
|
89
|
+
| ---------------------------- | ------------------------------------------------- |
|
|
90
|
+
| `pnpm dev:all` | The whole service graph, via `vercel dev --local` |
|
|
91
|
+
| `pnpm dev` or `pnpm dev:eve` | One agent and the eve terminal UI |
|
|
92
|
+
| `pnpm dev:web` | The frontend without its agent services |
|
|
89
93
|
|
|
90
|
-
|
|
94
|
+
Generated transport routes go before a filesystem handler, or before authored routes when there is none. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove that route, and remove or rename that service, because `withEve` adds both. Names in the array form of `services` must be unique. Other services, routes, bindings, and Cron Jobs stay authored in `vercel.ts`.
|
|
95
|
+
|
|
96
|
+
Custom agent channel endpoints aren’t published automatically. Route each one to the generated service:
|
|
91
97
|
|
|
92
98
|
```typescript title="vercel.ts"
|
|
93
99
|
import { withEve } from "eve/vercel";
|
|
@@ -109,9 +115,9 @@ export default await withEve({
|
|
|
109
115
|
});
|
|
110
116
|
```
|
|
111
117
|
|
|
112
|
-
A Vercel project
|
|
118
|
+
A Vercel project uses only one configuration source, so remove `vercel.json` when adopting `vercel.ts`. Keep `eve` in the root package dependencies so Vercel can import `eve/vercel`. `withEve` discovers the workspace containing its evaluation directory; pass `{ root: "/absolute/workspace/path" }` as the second argument to select a different workspace root.
|
|
113
119
|
|
|
114
|
-
|
|
120
|
+
Callbacks follow the mount: a root agent at `/eve/v1` receives them at `/eve/v1/callback/*`, and a named mount such as `/eve/support` at `/eve/support/v1/callback/*`.
|
|
115
121
|
|
|
116
122
|
### Deploy the project
|
|
117
123
|
|
|
@@ -121,9 +127,9 @@ Deploy the linked project to production from its root:
|
|
|
121
127
|
eve deploy
|
|
122
128
|
```
|
|
123
129
|
|
|
124
|
-
`eve deploy` installs dependencies, runs `vercel deploy --prod --logs
|
|
130
|
+
`eve deploy` installs dependencies, runs `vercel deploy --prod --logs`, and pulls the project environment afterward. You can also push to a Git-connected Vercel project. Hosted Vercel builds set `VERCEL`, so `eve build` writes the deployment bundle under `.vercel/output`.
|
|
125
131
|
|
|
126
|
-
When `eve deploy` creates a new Vercel project, it configures trace sampling so traces appear in
|
|
132
|
+
When `eve deploy` creates a new Vercel project, it configures trace sampling so traces appear in [Agent Runs](../../observability/agent-runs). Pass `--no-trace-sampling` to skip this.
|
|
127
133
|
|
|
128
134
|
For non-interactive use, confirm the production deploy up front. `--project` links first, so a new project needs no separate `eve link`:
|
|
129
135
|
|
|
@@ -131,10 +137,10 @@ For non-interactive use, confirm the production deploy up front. `--project` lin
|
|
|
131
137
|
eve deploy --project your_project_name --non-interactive --yes
|
|
132
138
|
```
|
|
133
139
|
|
|
134
|
-
Vercel
|
|
140
|
+
Vercel configures these services from the build output:
|
|
135
141
|
|
|
136
142
|
- **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
|
|
137
|
-
- **Vercel Workflow**:
|
|
143
|
+
- **Vercel Workflow**: stores and resumes agent runs
|
|
138
144
|
- **Vercel Cron**: invokes authored schedules
|
|
139
145
|
- **Vercel Sandbox**: runs sandbox sessions selected by the default sandbox environment
|
|
140
146
|
|
|
@@ -147,7 +153,7 @@ curl https://your_agent.vercel.app/eve/v1/health
|
|
|
147
153
|
eve remote connect --url https://your_agent.vercel.app
|
|
148
154
|
```
|
|
149
155
|
|
|
150
|
-
For a workspace agent, include its
|
|
156
|
+
For a workspace agent, include its `/eve/<name>` mount:
|
|
151
157
|
|
|
152
158
|
```bash
|
|
153
159
|
curl https://your_agent.vercel.app/eve/support/v1/health
|
|
@@ -164,8 +170,6 @@ for beta access, pricing, retention, and tracing setup.
|
|
|
164
170
|
|
|
165
171
|
## Continue configuring production
|
|
166
172
|
|
|
167
|
-
Use these guides to secure and observe the deployed agent:
|
|
168
|
-
|
|
169
173
|
- [Authentication](../auth-and-route-protection): configure who can call the deployed agent
|
|
170
174
|
- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
|
|
171
175
|
- [Sandbox](../../sandbox): configure resources, isolation, and network access
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Workflow Worlds"
|
|
3
|
+
description: "Choose and configure the Workflow world that stores and resumes eve sessions on a self-hosted deployment."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A Workflow world is the backend that stores eve sessions so they survive restarts and redeploys. eve runs every session as a [Workflow SDK](https://workflow-sdk.dev/) workflow. The world stores each run's event log, step results, pending input, and streams, and queues the work that resumes it. eve uses Vercel Workflow on Vercel and the local world for `eve start`. A self-hosted deployment can select another world package without changing the agent.
|
|
7
|
+
|
|
8
|
+
## Compare worlds
|
|
9
|
+
|
|
10
|
+
| World | Storage | Processes | After an eve version upgrade |
|
|
11
|
+
| ----------------------------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
|
|
12
|
+
| [Local](#use-the-local-world) | Files under `.eve/.workflow-data` | One | Existing sessions cannot resume |
|
|
13
|
+
| [Postgres](#use-the-postgres-world) | A PostgreSQL database | Any number of replicas | Existing sessions cannot resume |
|
|
14
|
+
| [Vercel Workflow](./vercel) | Managed by Vercel | Managed by Vercel | Runs continue on their original deployments; eligible idle sessions can move to the new deployment |
|
|
15
|
+
|
|
16
|
+
On the local and Postgres worlds, a new build on the same eve version resumes existing sessions. See [Upgrade a self-hosted agent](./self-hosted-operations#upgrade-a-self-hosted-agent) for what happens when the eve version changes.
|
|
17
|
+
|
|
18
|
+
All three support compaction handoff, which moves a session to a fresh run while keeping its ID, event stream, and addresses; the Postgres world needs `@workflow/world-postgres` 5.0.4 or later. Vercel Workflow also supports moving eligible idle sessions between deployments. See [Execution model and durability](../../concepts/execution-model-and-durability#compaction-handoff).
|
|
19
|
+
|
|
20
|
+
## Use the local world
|
|
21
|
+
|
|
22
|
+
The local world is the default for `eve start` and needs no configuration. It stores run state under `.eve/.workflow-data` in the app directory. Mount that directory on persistent storage so runs survive process and container replacement.
|
|
23
|
+
|
|
24
|
+
Each `eve start` process accepts queue messages only from its own queue. Don't point `WORKFLOW_LOCAL_BASE_URL` at a load balancer, because another replica rejects forwarded messages with HTTP 401. To serve an agent from several replicas, use the [Postgres world](#use-the-postgres-world).
|
|
25
|
+
|
|
26
|
+
On startup, `eve start` queues pending and running local workflow runs again. Runs that were active when the previous process stopped continue when the eve version is unchanged. `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS=0` or `false` doesn't disable this recovery.
|
|
27
|
+
|
|
28
|
+
## Use the Postgres world
|
|
29
|
+
|
|
30
|
+
The [`@workflow/world-postgres`](https://www.npmjs.com/package/@workflow/world-postgres) package stores runs in PostgreSQL and queues their work with Graphile Worker. Every `eve start` process connected to the same database processes queued work, so you can run several replicas behind a load balancer.
|
|
31
|
+
|
|
32
|
+
1. Install the package in your app:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pnpm add @workflow/world-postgres
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
2. Select it in the root `agent.ts`:
|
|
39
|
+
|
|
40
|
+
```typescript title="agent/agent.ts"
|
|
41
|
+
import { defineAgent } from "eve";
|
|
42
|
+
|
|
43
|
+
export default defineAgent({
|
|
44
|
+
model: "anthropic/claude-opus-5.5",
|
|
45
|
+
experimental: {
|
|
46
|
+
workflow: {
|
|
47
|
+
world: "@workflow/world-postgres",
|
|
48
|
+
},
|
|
49
|
+
},
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
3. Set the connection string in the runtime environment with `WORKFLOW_POSTGRES_URL`. The package also reads `DATABASE_URL`. When neither is set, it connects to `postgres://world:world@localhost:5432/world`.
|
|
54
|
+
|
|
55
|
+
4. Create the schema before the first start:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pnpm exec bootstrap
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
With npm, run `npx --package @workflow/world-postgres bootstrap`. The command reads the same connection variables. Run it again before you start a build that upgrades `@workflow/world-postgres`, so the database has the new version's migrations.
|
|
62
|
+
|
|
63
|
+
5. Build and start the server as usual with `eve build` and `eve start`.
|
|
64
|
+
|
|
65
|
+
### Tune the Postgres world
|
|
66
|
+
|
|
67
|
+
The package reads these optional variables:
|
|
68
|
+
|
|
69
|
+
| Variable | Default | Description |
|
|
70
|
+
| -------------------------------------- | ------- | ------------------------------------------------ |
|
|
71
|
+
| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | `50` | Queued jobs each process runs at once |
|
|
72
|
+
| `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | `10` | Connections in each process's database pool |
|
|
73
|
+
| `WORKFLOW_POSTGRES_POLL_INTERVAL_MS` | `500` | Milliseconds between idle job fetches per worker |
|
|
74
|
+
|
|
75
|
+
Graphile Worker recommends a pool size of at least the worker concurrency plus 2. With the default concurrency, set `WORKFLOW_POSTGRES_MAX_POOL_SIZE=52`, and size the database's connection limit for every replica's pool. See the [package README](https://www.npmjs.com/package/@workflow/world-postgres) for the full list.
|
|
76
|
+
|
|
77
|
+
The Postgres world stores workflow inputs, outputs, and stream contents in the database without encryption, and it keeps the records of finished runs until you delete them. Protect database access and backups, and see [Manage run data](./self-hosted-operations#manage-run-data) for retention.
|
|
78
|
+
|
|
79
|
+
## Use another world
|
|
80
|
+
|
|
81
|
+
Select any installed Workflow world package in the root `agent.ts`:
|
|
82
|
+
|
|
83
|
+
```typescript title="agent/agent.ts"
|
|
84
|
+
import { defineAgent } from "eve";
|
|
85
|
+
|
|
86
|
+
export default defineAgent({
|
|
87
|
+
model: "anthropic/claude-opus-5.5",
|
|
88
|
+
experimental: {
|
|
89
|
+
workflow: {
|
|
90
|
+
world: "@acme/eve-workflow-world",
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The package must export a default factory or `createWorld()` function. It reads credentials and host options from runtime environment variables, not `agent.ts`. If the package must stay external in hosted output, list it in `build.externalDependencies`.
|
|
97
|
+
|
|
98
|
+
Install a world built against the same `@workflow/*` major version as your eve release, currently `5.x`. eve checks the world's `@workflow/core` or `@workflow/world` dependency at startup, and fails with the version to install when the major versions differ.
|
|
99
|
+
|
|
100
|
+
See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the Workflow SDK abstraction, and [agent.ts](../../agent-config#workflow-world) for the configuration field.
|