pyagentos-sdk

Official Python SDK for AgentOS, the operating system for agent-run companies.

• Run hosted agents from your code: invoke, invoke_stream, conversations, and replies to agents that ask a question.
• Report agents that run in your own code: runs, events, spans and token usage, with the same history, alerts and reports as hosted agents.

Events are queued and sent from a background thread, with retries. If AgentOS is slow or down, your agent keeps running.

Install

pip install pyagentos-sdk

The package is pyagentos-sdk; import it as agentos. Python 3.10+.

Quick start

Create a key on your agent's Keys tab and set it in the environment:

export AGENTOS_API_KEY=aos_agent_...
export AGENTOS_AGENT_ID=...

Run a hosted agent

from agentos import AgentOS

aos = AgentOS()

result = aos.invoke({"prompt": "Summarise yesterday's tickets"})
if result.status == "completed":
    print(result.output)
# A run can also pause: "awaiting_approval" or "awaiting_input" (answer it with aos.reply()).

for event in aos.invoke_stream({"prompt": "Draft a reply"}):
    if event["type"] == "chunk":
        print(event["text"], end="", flush=True)

Report your own agent

with aos.start_run(input={"ticket": 42}) as run:
    step = run.start_span("classify", kind="step")
    run.emit_tool_call("search", {"q": "refund policy"})
    step.end()
# Completed when the block ends; failed, with the traceback, if it raises.

Or end the run yourself with complete() / fail() / cancel(). In serverless functions, call aos.flush() before returning.

LangChain

pip install "pyagentos-sdk[langchain]"

from agentos.langchain import AgentOSCallbackHandler

with aos.start_run() as run:
    chain.invoke(inputs, config={"callbacks": [AgentOSCallbackHandler(run)]})

Chains, models, tools and retrievers appear as a span tree with model names and token counts.

Documentation

Full reference, options and error types: agentos-ai.dev/docs/sdk-python. What changed: CHANGELOG.md.

License

MIT