Connect an agent runtime

Use this guide after creating your agent identity and connecting its runtime. The identity screen can generate a runtime token and enable reporting after you install it; the steps below also cover CLI/API setup. Enable agent work on your participating endpoint before configuring callbacks. This tutorial covers runtime integration with hosted and self-hosted deployments.

1. Prepare the deployment

The recorded hosted release provisions the infrastructure for opted-in endpoints. For self-hosting, the operator must enable agent work and recovery after applying the migrations and configuring private attachment storage, queues, secret storage, and scheduled maintenance. Self-hosting operators should use the repository's docs/agent-work-operations.md. The existing examples/agent-work/wrangler.local.toml is a local configuration, not a production deployment template.

2. Configure an opted-in endpoint

Create an HTTPS webhook or agent-runtime endpoint and publish its route. Configure the endpoint with config.agent_work: true. If you want automatic human decision delivery, also set config.decision_url to your runtime's HTTPS decision endpoint and use endpoint auth_config: { type: "bearer", secret_ref: "<stored-secret-reference>" }. Automatic decision delivery resolves that stored endpoint secret; there is no separate decision-secret config field.

The API accepts endpoint configuration through PUT /v1/endpoints/{endpoint_id} with a config object; preserve existing URL/timeout settings and send the current ETag in If-Match. Operator API credentials manage this setup; they should not be distributed to the runtime.

Provision a runtime credential:

agentowl --json runtime-credentials create <endpoint_id> --days 30

Store the returned token as a runtime secret. It authorizes callbacks and permitted content retrieval; the public credential ID in a handoff is not the token. See credential scope and rotation.

3. Accept the handoff and report work

Keep durable delivery acceptance. Opted-in envelopes include work_id, conversation_id, generation, a callback URL, and a public credential ID. Retried deliveries reuse the work identity; intentional replay creates new work.

POST a versioned accepted callback to the supplied URL with your runtime token. Preserve callback ID, sequence, timestamp, and body on retry. Follow with progress, a needs_input request, or an outcome. The reference has complete schemas and HTTP failure guidance.

4. Ask for a decision

A needs_input approval must identify the exact action, digest, request revision, allowed decisions, and expiry. Operators review the request in Needs attention or the CLI. The runtime deduplicates decision IDs, checks revision/action identity and expiry, and returns an acceptance receipt before reporting any execution outcome.

A receipt does not prove execution. Rejection, expiry, and replacement action revisions must not authorize the old action. See questions and approvals.

5. Verify the complete local scenario

The source checkout includes a deterministic SQLite receiver in examples/agent-work/receiver.py. It uses Python's standard library and accepts handoffs at /events and decisions at /decisions. Its required settings are RUNTIME_TOKEN and RECEIVER_SECRET; set AGENTOWL_ORIGIN to the operator's API origin. RECEIVER_DB chooses persistent state and PORT defaults to 8789. These are fixture results, not real tool actions.

The integration check provisions a local database and credentials, launches that receiver, sends an attachment-bearing handoff, observes acceptance and needs_input, submits a decision through the CLI, verifies its receipt and completed callback, and checks duplicate handling:

node --test --import tsx packages/worker/src/services/agent-work-receiver.test.ts

Run from repository root after installing workspace dependencies. This is a self-contained local API/CLI/receiver check; you do not need hosted access. The baseline signed receiver and this bearer-authenticated runtime fixture are separate examples with different authentication and purposes.

6. Connect your runtime

Replace fixture processing with your runtime's queue and execution. Preserve stable work/callback/decision identities, authenticated attachment retrieval, and conversation boundaries. Test retry, expiry, credential revocation, and recovery before enabling real traffic. Use the introduction to review ownership boundaries and the reference for exact limits.