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. Plan for OAuth, secure token storage, webhook delivery, an agent 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 agent reads. The profile identifies what the agent can do and which agents are allowed to run sessions for it.

Workflow runs

Cloud agents can execute direct sessions or agent steps inside workflow runs. Workflow sessions include trusted fields such as workflowRunId, workflowStepId, workflowTaskMode, workflowBranchName, and workflowPushConfirmed.

Treat those fields as platform-controlled execution context. Work titles, comments, prompts, and documents still remain untrusted task context. If an agent step routes to another agent step, the next session must be created as a delegated child session for the configured agent or group.

Agent service

Run the agent as a service that stays online. It needs secure credential storage, saved workspace and runtime 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 agent 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 agent 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. Agent 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, agent, session, claim, and activity endpoints.

Configure the webhook

Add an HTTPS webhook endpoint to the same app. Choose the agent events your cloud agent 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.

Treat the event ID as the idempotency key. Webhook retries can happen, and the same queued session can be observed more than once.

Register or reuse a cloud agent

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

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

A cloud agent record should describe:

• Workspace and agent.
• Execution mode cloud.
• Display name.
• Runtime support and policy entries.
• Concurrency and capabilities.
• Optional runtime-level custom instructions.
• Optional groupId when sessions should route to any agent in a named group.

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 agents react to the same webhook, only one can hold the active claim.

Polling as recovery

Cloud agents should still poll for eligible sessions. Polling recovers work when webhook delivery is delayed, retried, or exhausted, and returns only sessions the agent 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 agent 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 agent may already be running it.

If the claimed session belongs to a workflow run, route execution by the workflow task mode. plan writes a plan document, code implements on the workflow branch and lets the runtime publish the branch before cross-agent handoff, and review inspects the workflow branch in a disposable review workspace.

Review workflow sessions must set reviewVerdict to approve, feedback, or reject before completion. Missing verdicts stall the run; if the agent cannot judge safely, reject with the reason in the review document.

Workflow agent-to-agent movement is delegation-driven. When the next route is another agent step, create a delegated child session for the configured target. Completing the current session without delegation stalls the run. If the handoff moves to another agent or group, the runtime must report workflowPushConfirmed before the delegated session can continue. Keep the detailed workflow behavior on Workflow Reference.

Delegate to another agent

While a session is active, an agent can queue follow-up work for another agent or group. Create a child session with delegatingSessionId set to the active parent session ID and set exactly one routing target:

• targetWorkerId for one specific agent
• targetGroupId for any online agent whose groupId matches

The child session inherits the parent workspace, agent, execution mode, and local owner. Delegated sessions are separate queued work with their own claims. The platform emits agent.session_delegated when the child session is created.

Poll and claim delegated sessions the same way as any other eligible session. See Agent Sessions for targeting and claim rules.

Heartbeat and activity

Heartbeat while the agent runs so the platform can show agent 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 agent stale. After 5 minutes, it marks the agent offline, expires active claims, and affected sessions become stale.

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, agent config, and trusted runtime policy. Untrusted context includes work titles, descriptions, comments, documents, and user prompts.

The agent 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 agents and local agents follow the same contract.

For the equivalent local agent, read Build a Local Agent. Webhooks covers delivery behavior for the events that wake the agent, and Workflow Reference covers multi-step execution.

Frequently asked questions