Skip to main content
The Python SDK is a thin async wrapper around the Horizons HTTP API.
base_url points to your self-hosted horizons_server instance (or your own server built on horizons_core).
It uses:
  • httpx for async HTTP
  • pydantic for typed models

​
Install

pip install horizons

​
Create a client

import uuid
from horizons import HorizonsClient

org_id = uuid.UUID("00000000-0000-0000-0000-000000000000")

async with HorizonsClient(
    "http://localhost:8000",
    org_id,
    agent_id="agent:demo",
    # api_key="hzn_<uuid>.<secret>",
) as client:
    handle = await client.onboard.create_project()
    print(handle.project_id)

​
Publish events

await client.events.publish(
    topic="demo.hello",
    source="demo",
    payload={"hello": "world"},
    dedupe_key="demo:1",
)

​
Run agents

result = await client.agents.run(agent_id="dev.noop", inputs={"prompt": "hello"})
print(result.run_id)

​
Propose and approve actions

from horizons import models

action_id = await client.actions.propose(
    agent_id="agent:demo",
    action_type="demo.notify",
    payload={"message": "hello from python sdk"},
    risk_level=models.RiskLevel.low,
    dedupe_key="python-sdk-action-1",
    context={"source": "docs"},
)

await client.actions.approve(action_id, reason="docs demo")
pending = await client.actions.pending(limit=20, offset=0)
print("pending:", len(pending))

​
Stream agent runs (SSE)

async for event in client.agents.chat_stream(agent_id="dev.noop", inputs={"prompt": "hello"}):
    print(event)