# aal-sdk (Python)

Python SDK for the [Agent Action Ledger](https://agentink.dev) API. Full parity with the TypeScript SDK.

## Installation

```bash
pip install aal-sdk
```

With optional integrations:

```bash
pip install aal-sdk[anthropic]  # Anthropic client wrapper
pip install aal-sdk[mcp]        # MCP server wrapper
```

## Quick Start

```python
import asyncio
from aal_sdk import AALClient

async def main():
    client = AALClient({
        "api_url": "https://api.agentink.dev",
        "api_key": "your-api-key",
    })

    session = client.start_session({"agent_id": "my-agent"})

    session.log_action({
        "action_type": "TOOL_CALL",
        "tool_name": "get_weather",
        "parameters": {"city": "London"},
        "response": {"temp": 15},
        "status": "SUCCESS",
        "latency_ms": 42,
    })

    await client.shutdown()

asyncio.run(main())
```

## Auto-Instrumentation

### Anthropic Client

```python
from aal_sdk import AALClient
from aal_sdk.anthropic import wrap_anthropic_client
from anthropic import AsyncAnthropic

client = AALClient({"api_url": "...", "api_key": "..."})
session = client.start_session({"agent_id": "claude-agent"})

anthropic = wrap_anthropic_client(AsyncAnthropic(), session)
# All tool_use blocks are now automatically logged
```

### MCP Server

```python
from aal_sdk import AALClient
from aal_sdk.mcp import wrap_mcp_server
from mcp import Server

client = AALClient({"api_url": "...", "api_key": "..."})
session = client.start_session({"agent_id": "mcp-agent"})

server = Server("my-server")
wrap_mcp_server(server, session)
# All tool calls are now automatically logged
```

## API Reference

### AALClient

- `AALClient(config)` -- Create a client with `api_url`, `api_key`, optional `flush_interval` and `batch_size`
- `start_session(config)` -- Create a new session (returns `AALSession`)
- `session(session_id, agent_id)` -- Get a handle to an existing session
- `get_events(params)` -- Query events with optional filters
- `get_session(session_id)` -- Get session details
- `shutdown()` -- Drain buffer and close connections

### AALSession

- `log_action(input)` -- Log an action event (buffered, auto-flushed)

### Wrappers

- `wrap_anthropic_client(client, session)` -- Auto-log Anthropic tool_use blocks
- `wrap_mcp_server(server, session)` -- Auto-log MCP tool calls

## Documentation

Full documentation at [agentink.dev/docs](https://agentink.dev/docs).

## License

MIT
