Metadata-Version: 2.4
Name: pyagentos-sdk
Version: 0.2.0
Summary: AgentOS Python SDK — instrument agents with runs, events, and tasks
Project-URL: Homepage, https://agentos-ai.dev
Project-URL: Repository, https://github.com/bernabranco/agentos
Author: AgentOS
License: Apache-2.0
Keywords: agentos,agents,ai,langchain,observability,sdk
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# pyagentos-sdk

Official Python SDK for [AgentOS](https://agentos-ai.dev) — instrument your AI agents with runs, events, and tasks.

> The PyPI package is `pyagentos-sdk` (the `agentos-*` namespace was already claimed on PyPI by an unrelated project). The Python import name stays `agentos` for clean code.

The SDK is a thin client over the AgentOS API. Your agent code runs wherever you want; AgentOS observes it.

## Install

```bash
pip install pyagentos-sdk
```

For LangChain integration:

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

## Quick start

Generate an API key from your agent's page in the AgentOS dashboard, then pick a path:

### Calling a hosted agent

For agents you've defined in AgentOS — `invoke()` runs the agent server-side and returns its output:

```python
import os
from agentos import AgentOS

aos = AgentOS(
    api_key=os.environ["AGENTOS_API_KEY"],
    agent_id=os.environ["AGENTOS_AGENT_ID"],
)

result = aos.invoke({"prompt": "Hello"})
print(result["output"])
```

### Instrumenting your own agent

For agents that run in your own code — `start_run` / `emit` / `complete` reports them to AgentOS for observability:

```python
import os
from agentos import AgentOS

aos = AgentOS(
    api_key=os.environ["AGENTOS_API_KEY"],
    agent_id=os.environ["AGENTOS_AGENT_ID"],
)

run = aos.start_run(input={"prompt": "Hello"})

try:
    run.emit("step.completed", {"step": 1})

    # ... do work ...

    run.complete(output={"result": "Done"})
except Exception as e:
    run.fail(error_message=str(e))
    raise
```

`emit(type, payload, level)` is non-blocking — events are buffered and flushed on a timer (default 500 ms) or when the buffer fills (50 events). Call `run.flush()` if you need to be sure pending events are sent before the process exits. `run.complete()` and `run.fail()` flush automatically.

## LangChain integration

Drop in `AgentOSCallbackHandler` to mirror LangChain runs into AgentOS automatically:

```python
from agentos import AgentOS
from agentos.langchain import AgentOSCallbackHandler
from langchain_anthropic import ChatAnthropic

aos = AgentOS(api_key=..., agent_id="...")
run = aos.start_run()

model = ChatAnthropic(callbacks=[AgentOSCallbackHandler(run)])
model.invoke("What's the weather in SF?")

run.complete()
```

`langchain-core` is an optional dependency — only install it if you use the LangChain handler (`pip install "pyagentos-sdk[langchain]"`).

## Configuration

```python
AgentOS(
    api_key="aos_...",
    agent_id="...",
    base_url="https://agentos-ai.dev",  # optional — production default; override for self-hosted / local dev
    batch_interval_ms=500,              # flush events every 500 ms
    batch_size=50,                      # max events per batch
    disabled=False,                     # set True in tests for a no-op client
    timeout_seconds=10.0,               # httpx request timeout
)
```

## Errors

```python
from agentos import (
    AgentOSError,            # base class
    AgentOSAuthError,        # 401 — invalid/revoked key
    AgentOSValidationError,  # 400 — server-side validation failed
    AgentOSRateLimitError,   # 429 — ingest rate limit exceeded
)
```

## Requirements

- Python 3.10+
- An AgentOS workspace with an agent + API key ([sign up](https://agentos-ai.dev))

## License

Apache-2.0
