Metadata-Version: 2.5
Name: pyagentos-sdk
Version: 0.3.0
Summary: AgentOS Python SDK: run hosted agents, and report runs, events and spans from your own.
Project-URL: Homepage, https://agentos-ai.dev
Project-URL: Repository, https://github.com/bernabranco/agentos
Author: AgentOS
License: MIT
License-File: LICENSE
Keywords: agentos,agents,ai,langchain,observability,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: test
Requires-Dist: langchain-core>=0.3; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# pyagentos-sdk

Official Python SDK for [AgentOS](https://agentos-ai.dev), 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

```bash
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:

```bash
export AGENTOS_API_KEY=aos_agent_...
export AGENTOS_AGENT_ID=...
```

### Run a hosted agent

```python
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

```python
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

```bash
pip install "pyagentos-sdk[langchain]"
```

```python
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](https://agentos-ai.dev/docs/sdk-python). What changed: [CHANGELOG.md](./CHANGELOG.md).

## License

MIT
