Build a Cloud Agent

Build a cloud agent when queued work should run without relying on someone's laptop.

Cloud agents stay online and can be shared by team members. This is the advanced path. Plan for OAuth, secure token storage, webhook delivery, a worker loop, session claims, and user-visible progress.

Before you build

OAuth app

Create an OAuth app so a workspace member can approve your agent before it reads workspace data, claims sessions, or reports activity. Manage the app from Settings -> Apps.

Agent profile

People send an initiative, bug, or todo to an agent profile. That work item is the spec the cloud worker reads. The profile identifies what the agent can do and which workers are allowed to run sessions for it.

Worker service

Run the worker as a service that stays online. It needs secure credential storage, saved workspace and worker IDs, policy checks, concurrency limits, logging, and a way to finish, fail, or release every claimed session.

Webhook endpoint

Expose an HTTPS endpoint for agent events. The webhook wakes the service; the claim decides which worker actually runs the session.

Polling recovery

Keep a polling loop even when webhooks are enabled. Polling recovers work when delivery is delayed, retried, or exhausted.

Do not use API Keys for agent execution. Agent endpoints require OAuth user tokens.

Start from an example

The OAuth login example is a good way to verify the auth flow before adding worker logic.

Webhook templates are available for Heroku, Cloudflare, Vercel, and Netlify. They help you stand up a receiver, verify delivery, and then add the session claim loop.

Configuration model

Cloud agents have three configuration surfaces:

Manage the OAuth app and webhook from Settings -> Apps. Worker runtime config stays with the service that executes the work.

Create the OAuth app

Create an OAuth app from Settings -> Apps. Configure the app identity, callback URLs, OAuth settings, and any policy or terms URLs your consent screen needs.

A confidential OAuth client fits cloud services that can keep a client secret on the server. Store access and refresh credentials securely, scoped to the user or installation model your integration supports.

After authorization, use the OAuth access token for agent profile, worker, session, claim, and activity endpoints.

Configure the webhook

Add an HTTPS webhook endpoint to the same app. Choose the agent events your cloud worker needs.

Set or generate a verification key and verify the endpoint. Delivery uses CloudEvents JSON and includes the optional X-One-Webhook-Key header.

Store the verification key in your receiver and compare it before processing the event. Return 2xx after the event is accepted.

Use the event ID for idempotency. Webhook retries can happen, and the same queued session can be observed more than once.

Register or reuse a cloud worker

Find or create a worker for the workspace, agent, and cloud runtime.

Store the returned agentId and workerId in your service config. If the saved worker is rejected later, stop that worker path and require reconfiguration.

A cloud worker record should describe:

• Workspace and agent.
• Execution mode cloud.
• Worker name or display label.
• Runtime support and policy entries.
• Concurrency and capabilities.
• Optional worker-level custom instructions.

Webhook plus claim flow

The webhook is only the notification. Agent endpoints claim and update the session:

flowchart TD
  Queue["Session queued"]
  Webhook["Webhook received"]
  Fetch["Fetch eligible sessions"]
  Claim["Claim one session"]
  Execute["Execute in cloud"]
  Activity["Emit activity"]
  Finish{"Finish"}
  Complete["Complete"]
  Fail["Fail"]
  Release["Release"]

  Queue --> Webhook --> Fetch --> Claim --> Execute --> Activity --> Finish
  Finish --> Complete
  Finish --> Fail
  Finish --> Release

A webhook is not a lease. If two workers react to the same webhook, only one can hold the active claim.

Polling as recovery

Cloud workers should still poll for eligible sessions. Polling recovers work when webhook delivery is delayed, retried, or exhausted, and returns only sessions the worker is allowed to claim.

Claim before running work

Claim the session before running code, calling a model, or starting an external job. The claim is the lock that tells every other eligible worker to leave that session alone.

Pass leaseSeconds if you need a specific lease duration. The default is 900 seconds. Include the returned claimId in every activity, metadata update, completion, failure, and release call.

If the claim fails with a conflict, stop handling that session from this event. Another worker may already be running it.

Heartbeat and activity

Heartbeat while the worker runs so the platform can show worker status and detect stale execution. Heartbeats do not create work or extend active claims. Send a heartbeat every 10 seconds. If no heartbeat arrives for 12 seconds, the platform marks the worker stale. After 5 minutes, it marks the worker offline and expires active claims.

Use activities for meaningful user-visible progress, not every heartbeat. The activity model lives in Agent Sessions.

Trust boundary

Keep trusted instructions separate from untrusted work context.

Trusted instructions come from platform policy, the agent profile, worker config, and trusted runtime policy. Untrusted context includes work titles, descriptions, comments, documents, and user prompts.

The worker must enforce policy before filesystem access, shell execution, network access, workspace writes, or external side effects.

Finish the session

End every claimed session with a terminal outcome: complete, fail, or release. Keep the detailed lifecycle behavior in Agent Sessions so cloud workers and local workers follow the same contract.

For the equivalent local workflow, read Build a Local Agent. Webhooks covers delivery behavior for the events that wake the worker.

Frequently asked questions