Agent runtime
How the optional agent service is deployed, how the web app decides whether it is available, and how a run, its workspace, skills and decisions fit together.
The agent is a separate service next to the web application, and it is optional. A deployment without it is a complete web app: AI tasks and chat call the configured channels directly through /app/ai, /app/chat and /api/chat. When the service is deployed, the web app authenticates the user, checks ownership and forwards signed requests to it. The service runs the agent loop, the sandboxes and its own background worker. The browser calls only the web app's /api/agent/* routes.
Two processes, one direction of trust
apps/agent-service is a Node process installed by the agent-starter template. The web app reaches it in one of two ways:
| Transport | When it is used | How it is configured |
|---|---|---|
url | A Node server, a container on another platform, or local development | AGENT_SERVICE_URL in the web app's environment |
container | A Cloudflare Worker with the agent as a Cloudflare container | The AGENT_SERVICE Durable Object binding in wrangler.jsonc |
Both transports send the same signed request. AGENT_INTERNAL_SIGNING_SECRET authenticates requests between the two processes, and AGENT_RESOURCE_GRANT_SECRET signs the short-lived tokens used to reach a stored file. The service never receives session, OAuth or payment variables and refuses to start when one is present in its environment, because it runs untrusted code in sandboxes.
On Cloudflare every request goes to one named container instance. The service holds stream subscriptions, runs in progress and the sandbox pool in memory, so requests for one run must reach the same process. The Worker's Cron Trigger sends that container one maintenance round when runs are unfinished, which also keeps it awake.
Availability is one answer
getAgentAvailability() returns whether this deployment can run the agent. It reads only plugin state, the environment and the database dialect and does not load the agent runtime, so the console layouts can call it on every navigation.
| Reason | Meaning |
|---|---|
plugin_disabled | The agent-starter plugin is switched off in Settings → Plugins. |
database_not_transactional | The database is Cloudflare D1, which has no interactive transactions. |
service_not_configured | Neither AGENT_SERVICE_URL nor the AGENT_SERVICE binding is present. |
signing_secret_missing | AGENT_INTERNAL_SIGNING_SECRET is not set. |
Every agent entry uses that result:
- Navigation entries that carry
requires: "agent"are hidden. /app/agentand/app/imageexplain that the agent service is not deployed and what to do next./api/agent/*returns503with the codeagent_unavailable.
Available does not mean ready. The readiness checks below report whether the service has a model route and a sandbox.
The database must have transactions
Accepting a run, answering a question, resolving an approval and claiming a background task are each several statements that must commit together. The agent repositories therefore reject a database without interactive transactions before reading or writing anything, with agent_requires_transactions.
| Database | Agent |
|---|---|
| Postgres | Supported. On a Worker the web app connects through Hyperdrive and the container connects directly. |
| SQLite on Node | Supported. The repository facade wraps the better-sqlite3 connection so that asynchronous transaction callbacks run one after another. |
| Cloudflare D1 | Not supported. The web app runs; the agent entries do not appear. |
The engine behind a run
packages/agent-runtime composes the run loop from DeepSeek Harness packages (@deepseek-ai/cordis and @deepseek-ai/dsh-*): the agent loop, sessions persisted as an event log, compaction, a token meter, pruning of old tool results and provider retry. The versions are pinned, and one package carries a patch from patches/ applied through pnpm patchedDependencies.
Host code does not import those packages. It depends on the product-facing contracts in runtime-contracts.ts, so the engine can change inside the package without touching src/server or apps/agent-service. pnpm validate:dsh-runtime checks the pins, that business code does not import the engine directly, and runs the engine's contract tests.
No web request path loads the runtime. Routes import runtime helpers through narrow subpath exports and never through the package index. pnpm validate:optional-agent checks the built server for it.
Threads, runs and workspaces
A thread holds conversation history. A run is one attempt to answer a message. POST /api/agent/runs supplies the message, an idempotency key and optionally an existing thread, a branch or a selected skill. Each run owns its workspace. Attachments and small workspace files are staged into that run before its first model turn. A later run cannot read an earlier run's workspace. A quote of an artifact is carried into the new run explicitly.
The run pins the primary skill, any capability skills, its scene and tool set. This keeps a resumed run on the same effective configuration even if the registry's latest skill version changes. The service resolves the active AI scene route and settles reserved credits through the server-side ledger. Missing model, sandbox or storage configuration is reported as an error, and the service produces no sample output. The number of runs one user may have in progress comes from the plan's concurrentAgentTasks entitlement.
The response to a new run and the thread snapshot carry routing: the scene, the primary skill and the plugin the run went to. The workbench uses it to follow a request that was routed automatically.
States and decisions
| State | Meaning | What happens next |
|---|---|---|
queued | Accepted but not yet executing | The worker starts it, or it fails or is cancelled before execution. |
running | Model and tools are executing | It may finish, fail, be interrupted, or wait for a person. |
waiting_user | The run asked for information | The owner answers the specific user request. |
waiting_approval | A tool action requires consent | The owner approves or denies the specific action. |
completed, failed, canceled, interrupted | Terminal outcomes | The same run does not return to running; a new run is needed for further work. |
An approval request carries a fingerprint and policy version. The response must return both with the decision, so a changed or expired action cannot be approved using an old button. A user request is a question and uses a different endpoint. Reconnecting a stream resumes the view of a run and does not create a second run. Cancellation is a request to the service. It does not undo an action that has already finished.
Skills, tools and the sandbox
Platform skills live in agent-skills/ in the source checkout, and a capability plugin ships its own skill inside its plugin folder. pnpm agent:publish-skills packages them in object storage and the skill registry. The runtime reads authorized published versions and does not read local files. A run can choose a skill automatically or pin an authorized version. agent-skills/ is separate from skills/, which provides workflows to coding assistants.
Tools that need code execution use the sandbox configured in /admin/config/sandbox. Search and crawl tools use the providers configured in /admin/config/search. Connector actions require their own account authorization. Resource previews and downloads use owner-scoped, short-lived grants, so a stored artifact never becomes a public URL.
Capabilities beyond the core set, such as an image agent, are plugins of the one workbench. They declare scenes, skills, cards and operations. The host checks them and switches them off with the plugin. See Plugins and Agent plugins.
Readiness and failure boundaries
GET /healthz on the agent service reports process liveness. GET /readyz checks database reachability, schema version, object storage and usable provider configuration. It returns 503 while any required check is not ready. The /app/agent composer has its own narrower check: an active agent.general text route with its referenced secrets, plus a configured sandbox. Search and crawl are needed only for tools that use them. The readiness checks do not simulate a provider call.
The web app's own background work (fulfilment retries and unfinished AI tasks) runs in the web app's scheduled jobs and not in the agent service's loop, so it continues without the agent. See Background jobs.
Files
Next steps
- Run the agent starter: configuration, startup and checks.
- Plugins: how agent capabilities are installed and switched on and off.
- Credits: reservation and settlement.