Skip to main content
Use this runbook for local/staging/prod wiring of the managed-agents BFF surface.

​
Required backend env vars

  • HORIZONS_PRIVATE_BASE_URL
  • HORIZONS_PRIVATE_SERVICE_API_KEY
Recommended:
  • explicit ANTHROPIC_VERSION

​
Service responsibility

ServiceResponsibility
Backendedge auth, org scoping, route allowlist, upstream forwarding
horizons-privateupstream Anthropic-compatible managed-agents implementation
synth-ai clientsconsumer SDK surface (client.managed_agents)

​
Smoke checks

​
1) Health

curl -sS https://api-dev.usesynth.ai/api/managed-agents/anthropic/v1/health \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "anthropic-version: 2023-06-01"

​
2) Session create + list events

curl -sS https://api-dev.usesynth.ai/api/managed-agents/anthropic/v1/sessions \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{"agent":"agent_123","environment_id":"env_123","title":"smoke"}'

curl -sS "https://api-dev.usesynth.ai/api/managed-agents/anthropic/v1/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

​
3) SSE connect/read/close

curl -N -sS "https://api-dev.usesynth.ai/api/managed-agents/anthropic/v1/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $SYNTH_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "accept: text/event-stream"

​
Failure signatures

SymptomLikely cause
Proxy 5xx config errormissing backend HORIZONS_PRIVATE_* env
Proxy 401/403backend edge auth failed (SYNTH_API_KEY)
Upstream operation mismatchroute not in Phase 1 allowlist or header mismatch

​
Staging walkthrough (timestamped)

Latest recorded smoke validation timestamp for this surface: 2026-04-14. Expected checks:
  1. health returns 200
  2. session create returns 200/201
  3. events list returns 200
  4. events stream connects with text/event-stream and clean close
Script used in backend CI/runtime notes: 
uv run scripts/ci/smoke_horizons_private_anthropic_proxy.py \
  --base-url https://api-dev.usesynth.ai \
  --api-key "$SYNTH_API_KEY" \
  --session-id <id> \
  --anthropic-beta managed-agents-2026-04-01
Proof notes are tracked in horizons-private/docs/current/openaireview_verification_push_notes.md.

​
End-to-end transcript (shape reference)

Use this as a practical request/response sequence template.

​
Create agent

Request: 
POST /api/managed-agents/anthropic/v1/agents
Authorization: Bearer <SYNTH_API_KEY>
anthropic-version: 2023-06-01
anthropic-beta: managed-agents-2026-04-01
content-type: application/json

{
  "name": "Docs Agent",
  "model": "claude-sonnet-4-6",
  "tools": [{"type": "agent_toolset_20260401"}]
}
Response shape: 
{
  "id": "agent_abc123",
  "name": "Docs Agent"
}

​
Create environment

Request body shape: 
{
  "name": "docs-env",
  "config": {"type": "cloud", "networking": {"type": "unrestricted"}}
}
Response shape: 
{
  "id": "env_abc123",
  "name": "docs-env"
}

​
Create session

Request body shape: 
{
  "agent": "agent_abc123",
  "environment_id": "env_abc123",
  "title": "docs-smoke"
}
Response shape: 
{
  "id": "session_abc123",
  "status": "active"
}

​
Post event + stream

Post event body shape: 
{
  "events": [
    {
      "type": "user.message",
      "content": [{"type": "text", "text": "hello"}]
    }
  ]
}
Then connect: 
GET /api/managed-agents/anthropic/v1/sessions/{session_id}/events/stream
accept: text/event-stream
Typical stream sequence:
  1. user.message
  2. agent.message and/or agent.tool_use
  3. session.status_idle (safe close point for short-lived workflows)