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.

Cloud agents use webhooks as a wake-up signal. The worker still needs to fetch and claim a queued session before doing any work.

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 Apps.

Agent profile

People send an initiative, bug, or todo to an agent profile. That source work 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, including agent.session_queued when your service should wake up as soon as work is queued. Webhooks notify the service; they do not grant the right to run work.

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

Use the OAuth login example to verify the auth flow before adding worker logic.

Webhook templates are available for Heroku, Cloudflare, Vercel, and Netlify. Use them to 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 Apps. Worker runtime config stays with the service that executes the work.

Create the OAuth app

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

Use a confidential OAuth client when your cloud service 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, including agent.session_queued when the service should react as soon as work is queued.

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

Use the webhook as a notification, then use agent endpoints to 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.

Use polling when:

• The worker starts or restarts.
• A webhook arrives and you need the current claimable sessions.
• You need periodic recovery for missed notifications.
• You need to verify whether queued or stale sessions are still available.

Polling 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.

Use activities for user-visible progress:

• progress
• plan_updated
• external_url_updated
• awaiting_input
• completed
• failed
• policy_decision

Do not emit an activity for every heartbeat.

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, use Build a Local Agent. For webhook delivery details, use Webhooks. Operation names and schemas live in the API reference.

Frequently asked questions