> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rako.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Use Rako from Python agents and services.

# Python SDK

Use the Python SDK when building Python agents or backend services.

<Card title="Run the local Python example" href="https://github.com/rakohq/developer-docs/tree/main/examples/python-sdk-basic">
  Try the SDK against the mock AAP server with `AAP_API_KEY=aap_demo_key` and fake checkout data.
</Card>

```bash Install theme={null}
pip install agent-attribution-protocol
```

```python quickstart.py theme={null}
from agent_attribution_protocol import AAP

aap = AAP(api_key="your-api-key")

# 1. Search for offers
result = aap.search(vertical="sim", max_price=10, contract_months=0)
print(f"Found {result.count} offers")

# 2. Recommend an offer (records attribution)
rec = aap.recommend(
    session_id=result.session_id,
    offer_id=result.offers[0].id,
    context="User asked for cheap SIM with no contract",
)
print(f"Fallback URL: {rec.fallback_url}")

# 3. Initiate checkout
checkout = aap.checkout(
    session_id=result.session_id,
    recommendation_id=rec.recommendation_id,
)
print(f"Transaction: {checkout.transaction_id}")
```

## Client

### `AAP(api_key, base_url="https://api.rako.sh")`

Create a client. It can also be used as a context manager:

```python theme={null}
with AAP(api_key="your-api-key") as aap:
    result = aap.search(vertical="sim")
```

## Methods

### `aap.search(**kwargs)`

Search for offers.

| Option            | Type  | Description                                                    |
| ----------------- | ----- | -------------------------------------------------------------- |
| `vertical`        | str   | `sim`, `broadband`, `energy`, `flights`, `hotels`, `insurance` |
| `provider`        | str   | Filter by provider name                                        |
| `max_price`       | float | Maximum price                                                  |
| `min_data_gb`     | int   | Minimum data allowance for SIM offers                          |
| `contract_months` | int   | Contract length, where `0` means rolling                       |

### `aap.recommend(session_id, offer_id, context)`

Record a recommendation. This is the attribution event.

### `aap.checkout(session_id, recommendation_id, user_details)`

Initiate checkout for a recommended offer.

### `aap.get_session(session_id)`

Get session details including recommendations and conversions.

### `aap.verify_code(code)`

Verify an AAP Code is authentic.

## Mock conversion learning

The runnable SDK example reaches a mock checkout URL. To understand why checkout-link creation is separate from conversion recording, see [Mock Conversion Artifact](/guides/mock-conversion).

<CardGroup cols={2}>
  <Card title="PyPI" href="https://pypi.org/project/agent-attribution-protocol/" />

  <Card title="GitHub" href="https://github.com/rakohq/aap-python" />
</CardGroup>