Build a cloud agent

A cloud agent is a hosted runtime that can serve permitted workspace members without depending on one laptop. Webhooks reduce pickup latency; polling ensures queued work is still found when delivery is delayed or exhausted.

1. 1

   Create the OAuth client

   Register an OAuth app with the callback URLs and scopes required by your service. Complete user authorization and store tokens in a secret manager. Agent execution endpoints require OAuth user tokens.

2. 2

   Configure the service

   Store the workspace, agent profile, runtime IDs, encrypted OAuth state, webhook verification key, polling interval, concurrency, and trusted runtime policy. Keep this configuration separate from workspace-authored task context.

3. 3

   Register the cloud runtime

   Find or create a runtime with execution mode cloud, declared capabilities, concurrency, and optional group. Stop and require reconfiguration if a persisted identity later becomes invalid.

4. 4

   Configure webhook notification

   Add a verified HTTPS endpoint to the OAuth app, subscribe to the required agent events, validate the optional X-One-Webhook-Key, deduplicate by event ID, and return 2xx after accepting the event.

5. 5

   Add polling recovery

   Poll the agent-scoped session endpoint even when webhooks are healthy. Polling recovers sessions after delayed, retried, or exhausted delivery.

6. 6

   Claim and execute

   Fetch the current session and claim it before starting work. Include the returned claimId on metadata, activities, delegation, and every terminal mutation. Stop processing on a claim conflict.

7. 7

   Finish the session

   Complete successful work, fail unrecoverable work, or release work that stopped safely before useful execution. Keep runtime heartbeats separate from progress events.

Notification does not confer ownership of the session.

Cloud agent claim flow

Webhook and polling paths converge before the claim.

sequenceDiagram
  participant Platform as One Horizon
  participant Agent as Cloud agent
  participant Runtime as Execution runtime
  Platform->>Agent: Webhook wake-up
  loop Polling recovery
    Agent->>Platform: List eligible sessions
  end
  Agent->>Platform: Claim session
  Platform-->>Agent: claimId
  Agent->>Runtime: Execute trusted policy + untrusted context
  Runtime-->>Agent: Progress and metadata
  Agent->>Platform: Activity with claimId
  Agent->>Platform: Complete, fail, or release with claimId

Execution contract

Heartbeat while the service is available. Heartbeats report runtime health; they do not extend claims or replace progress activities. Emit activities for meaningful changes such as plans, external URLs, input requests, completion, failure, and policy decisions.

Workflow task mode controls whether the runtime plans, researches, codes, or reviews. Review completion requires approve, feedback, or reject. When a route crosses to another agent or group, create a delegated child session and confirm the shared branch has been pushed before handoff.

Treat platform policy, agent configuration, and service policy as trusted. Treat titles, descriptions, comments, documents, prompts, and resume input as untrusted. Enforce access and side-effect policy before filesystem, shell, network, workspace, or external-service operations.

Exact webhook, session, claim, activity, and runtime schemas live in the OpenAPI reference. Webhooks owns delivery behavior, and agent sessions owns leases, eligibility, delegation, resume, and terminal outcomes.