handoff schemaexecutor protocolproof ledgerOneAI brain

Reference: Agent OS

Standard handoff contracts, executor protocol, approval policy, proof callbacks, and execution result ledger. OneAI does not execute external actions.

Protocol model

Agent OS is a coordination protocol, not an executor runtime. OneAI owns planning, approvals, records, and verification metadata; external executors own real-world action.

Role	System	Responsibility
Planner	OneAI	Creates plans, context packets, handoff contracts, approval policies, proof policies, and ledger records.
Executor	OneClaw / OpenClaw / bot / external / human	Performs external actions only after approval policy allows execution.
Verifier	OneAI operator / admin	Reviews proof, marks proof verified, needs_review, or rejected, and closes operational trust loop.
Customer system	Your backend	Owns API keys, sends requests, stores business-side decisions, and keeps secrets out of browsers.

Non-negotiable execution boundary

OneAI never performs external actions through Agent OS. It can create the plan, approval policy, proof policy, handoff contract, and ledger record. OneClaw, OpenClaw, bots, customer systems, or humans perform the action and report proof/results back to OneAI.

1) Capabilities

List OneAI task capabilities plus Agent OS preview capabilities. This is a capability directory, not a workflow execution endpoint.

curl -s https://oneai-saas-api-production.up.railway.app/v1/capabilities \
  -H "x-api-key: YOUR_KEY" | jq

2) Agent Plan Contract

Create a standard plan object that can later be handed off to OneClaw, bots, external agents, or humans.

curl -s https://oneai-saas-api-production.up.railway.app/v1/agent-plans \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "objective": "Prepare a production launch checklist for OneAI",
    "constraints": ["Do not execute actions", "Every action must be verifiable"],
    "targetExecutor": "oneclaw",
    "riskLevel": "medium"
  }' | jq

3) Handoff Preview

Package a plan for an executor without triggering execution. This preserves the OneAI / OneClaw boundary.

curl -s https://oneai-saas-api-production.up.railway.app/v1/handoff/preview \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "objective": "Hand off a launch checklist to OneClaw",
    "targetExecutor": "oneclaw",
    "approvalRequired": true,
    "proofRequired": ["deployment log", "health check result"]
  }' | jq

4) Standard Handoff Contract

Create a stored Agent OS contract for OneClaw, OpenClaw, bots, external agents, or human operators. The contract includes approval policy, proof requirements, callbacks, and a ledger record.

curl -s https://oneai-saas-api-production.up.railway.app/v1/handoff/contracts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "objective": "Hand off a launch checklist to OpenClaw",
    "targetExecutor": "openclaw",
    "executorProtocol": "openclaw.v1",
    "riskLevel": "medium",
    "approvalMode": "manual",
    "proofRequired": ["execution log", "result summary"]
  }' | jq

5) Executor Protocol

Executor teams can inspect the OneAI Agent OS protocol and callback routes before integrating.

curl -s https://oneai-saas-api-production.up.railway.app/v1/executor-protocol \
  -H "x-api-key: YOUR_KEY" | jq

6) Approval, Proof, Result

Executors never need direct database access. They report approval, proof, and final results through standard callbacks.

Approve

curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/approval \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"status":"APPROVED","approvedBy":"operator"}'

Proof

curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/proof \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"executorRunId":"run_001","status":"RUNNING","proof":{"artifacts":[],"summary":"Started execution."}}'

Result

curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/result \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"executorRunId":"run_001","status":"SUCCEEDED","result":{"summary":"Completed."}}'

7) Executor lifecycle

Use this lifecycle when integrating OneClaw, OpenClaw, bots, external agents, or human operators.

contract_created

OneAI creates a handoff contract and stores an execution ledger record.

approval_decided

Approval is auto-approved by policy or waits for a manual approval callback/operator action.

executor_started

OneClaw, OpenClaw, bot, external agent, or human starts external work outside OneAI.

proof_received

Executor submits logs, URLs, screenshots, transaction references, JSON, or text proof.

proof_reviewed

Operator or policy reviews proof and marks it verified, needs_review, or rejected.

result_received

Executor submits the final result and status.

ledger_closed

OneAI keeps the full handoff/proof/result trail for customer and operator review.

8) Context Preview

Normalize business, thread, customer, memory, retrieval, and policy context before attaching it to Task Intelligence or Agent Plan requests.

curl -s https://oneai-saas-api-production.up.railway.app/v1/context/preview \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "threadId": "launch-thread-001",
    "customerId": "customer_123",
    "memoryHints": ["Customer prefers short practical plans"],
    "retrievalContext": [{ "title": "Launch notes", "text": "Ship API docs first." }],
    "policyHints": ["Do not execute external actions"]
  }' | jq

Execution boundary

OneAI is the intelligence and coordination brain. These Agent OS endpoints create capability metadata, plans, context packets, and handoff previews. They do not click buttons, call external tools, or execute real-world actions. Execution belongs to OneClaw, bots, customer agents, or human operators.

View protocol versioning

Messages

Models