Build a cloud agent

A cloud agent is a hosted harness that can serve permitted workspace members without depending on one laptop. Webhooks reduce pickup latency; polling finds queued work 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, harness IDs, encrypted OAuth state, webhook verification key, polling interval, concurrency, and trusted harness policy. Keep this configuration separate from workspace-authored task context.

3. 3

   Register the cloud harness

   Find or create a harness 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.

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 harness heartbeats separate from progress events.

Cloud agent claim flow

Webhook and polling paths converge before the claim.

sequenceDiagram
  participant Platform as One Horizon
  participant Agent as Cloud agent
  participant Env as Execution environment
  Platform->>Agent: Webhook wake-up
  loop Polling recovery
    Agent->>Platform: List eligible sessions
  end
  Agent->>Platform: Claim session
  Platform-->>Agent: claimId
  Agent->>Env: Execute trusted policy + untrusted context
  Env-->>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 harness 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 harness 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 harness schemas live in the OpenAPI reference. Webhooks owns delivery behavior, and agent sessions owns leases, eligibility, delegation, resume, and terminal outcomes.