Metadata-Version: 2.4
Name: agentblit
Version: 0.1.2
Summary: Agentic SDK for LLM agents with AgentBlit tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0

# AgentBlit Python SDK

Build LLM agents with:
- AgentBlit remote tools
- optional local Python tools
- streaming output
- approval-gated actions
- short-term memory with automatic summarization

## Install

```bash
cd agentblit-python
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
```

## Quick Start

```python
import asyncio
from agentblit import Agent, tool

@tool(description="Add two integers.")
def add(a: int, b: int) -> int:
    return a + b

async def main() -> None:
    agent = Agent(
        model="openai/gpt-4o-mini",
        api_key="YOUR_LLM_KEY",
        agentblit_api_key="YOUR_AGENTBLIT_KEY",
        system_prompt="You are a helpful assistant.",
        custom_tools=[add],
    )

    async for chunk in agent.run("What is 200 + 30? Use tools if needed."):
        print(chunk, end="")
    print()

asyncio.run(main())
```

---

## 1) Agent Initialization Configs

`Agent(...)` accepts:

| Key | Type | Required | Default | Values / Format | Use Case |
|---|---|---|---|---|---|
| `model` | `str` | Yes | - | `vendor/model` (for example: `openai/gpt-4o-mini`, `anthropic/claude-sonnet-4-0`, `gemini/gemini-2.0-flash`, `openrouter/openai/gpt-4o-mini`) | Select provider + model |
| `api_key` | `str` | Yes | - | LLM provider API key | Send model requests |
| `agentblit_api_key` | `str` | Yes | - | AgentBlit API key (`X-API-Key`) | Remote tools + analytics events |
| `agentblit_url` | `str` | No | `https://console.agentblit.com` | Valid base URL | Self-hosted or staging AgentBlit |
| `agent_id` | `str` | No | Auto-generated UUID | Any non-empty string | Reuse a stable agent identity across sessions/events |
| `system_prompt` | `str` | No | `""` | Any instruction text | Set assistant behavior |
| `max_history` | `int` | No | `5` | Integer `>= 1` | Keep recent messages before summarization |
| `max_tool_rounds` | `int` | No | `25` | Integer `>= 1` | Limit LLM-tool loop iterations |
| `debug` | `bool` | No | `False` | `True` or `False` | Enable verbose SDK logs |
| `timeout` | `float` (seconds) | No | `30.0` | Positive number | Control HTTP timeout for LLM + AgentBlit |
| `approval_callback` | `async (tool_name, args_dict) -> bool` | No | - | Async function | Approve/reject `needs_approval` tools |
| `custom_tools` | `list` | No | `[]` | Local `@tool` callables | Register app-specific local tools |

---

## 2) All SDK Features

- Vendor routing for `openai`, `anthropic`, `gemini`, and `openrouter`
- Remote AgentBlit tools (`/api/tools/list`, `/api/tools/call`)
- Local tools via `@tool`, `custom_tools`, and `agent.register_tool(...)`
- Approval-gated tools (`needs_approval`) with callback support
- Streaming responses with `async for chunk in agent.run(...)`
- Multi-round tool calling in one `run()`
- Memory summarization using `max_history`
- Default system guidance to use tools and available long-term memory tools (`retrieveRelevantMemory`, `updateMemory`) when needed
- Automatic analytics batching (`agent_init`, `user_prompt`, `llm_call`, `tool_call`, `tools_updated`, `agent_loop_error`)
- Custom analytics via `agent.track(event_type, properties)`

---

## 3) Examples

### Example 1: Basic Streaming Agent

```python
agent = Agent(
    model="openai/gpt-4o-mini",
    api_key="YOUR_LLM_KEY",
    agentblit_api_key="YOUR_AGENTBLIT_KEY",
    system_prompt="Be concise and accurate.",
)
```

### Example 2: Approval-Gated Tool

```python
async def approval_callback(tool_name: str, args_dict: dict) -> bool:
    print("Approve tool call?", tool_name, args_dict)
    return tool_name != "delete_production_data"

agent = Agent(
    model="openai/gpt-4o-mini",
    api_key="YOUR_LLM_KEY",
    agentblit_api_key="YOUR_AGENTBLIT_KEY",
    approval_callback=approval_callback,
)
```

## Repo Examples

- [`examples/basic_agent.py`](examples/basic_agent.py) - interactive terminal chat with remote tools.
- [`examples/custom_tools.py`](examples/custom_tools.py) - local `@tool` functions + AgentBlit tools.
