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

# Python Agent SDK

> Prefer fau-agent when integrating in Python — resolve, signed MCP, approvals, offline queue.

**Purpose:** connect a Python assistant without re‑implementing RFC 9421, MCP session
handling, or the offline queue.

**When to use this:** you are on Python (or Cursor is generating Python).

**When not to:** another language or runtime — implement [Connect your agent](https://docs.fau.run/developer/agents/getting-started.md)
against protocol `fau/1`. The SDK is a convenience, not the contract.

## Install

```bash theme={null}
pip install 'fau-agent[httpx]'
# from this repo:
# pip install -e 'sdk/python[httpx]'
```

Source: [`sdk/python`](https://github.com/ranagwho/Federated-Agent-Use/tree/main/sdk/python).

> [card] [Tutorial](https://github.com/ranagwho/Federated-Agent-Use/blob/main/sdk/python/examples/production_mail_agent.py)
>
> Manage User's Travel & Deliveries on a busy day. Agent access several kinds of mail, deals with mission permissions and offline nodes.

## First contact

Publish `identity.key_document()` at `https://<your-domain>/.well-known/fau-agent`
([Identity](https://docs.fau.run/developer/connect/identity.md)), then:

```python theme={null}
from fau_agent import Agent, AgentIdentity

identity = AgentIdentity.generate("assistant.example")
# identity.save("~/.fau-agent/identity.json")

agent = Agent(identity)

with agent.session("user@gmail.com") as node:
    node.probe()  # GET /.well-known/fau-node (unsigned)
    result = node.call("ask", {"question": "When is my next flight?"})

    if result.get("error") == "approval_required":
        # Show verified domain + match_code in your UI, then:
        result = node.call_with_retry_after_approval(
            "ask",
            {"question": "When is my next flight?"},
            on_approval=lambda p: print("waiting", p["match_code"]),
        )

print(result)
```

One-shot (blocks until allowed or timeout):

```python theme={null}
result = agent.ask(
    "user@gmail.com",
    "When is my next flight?",
    wait_for_approval=True,
)
```

## Claim enrollment (no public domain)

```python theme={null}
identity = AgentIdentity.generate("placeholder.local")
agent = Agent(identity)

with agent.session("n….relay.fau.run", as_hostname=True) as node:
    node.enroll("AB12CD34")  # claim from the user’s Mac / phone
    result = node.call("get_upcoming_travel")
```

Details: [Enroll](https://docs.fau.run/developer/connect/enroll.md).

## Offline queue

When live TLS fails, seal a signed tool call and park it on the relay. Persist the
reply private key **before** enqueueing:

```python theme={null}
from fau_agent import Agent, AgentIdentity, OutstandingRequestStore

agent = Agent(
    AgentIdentity.load("~/.fau-agent/identity.json"),
    outstanding=OutstandingRequestStore(),
)

queued = agent.enqueue_tool_call(
    "user@gmail.com",
    "ask",
    {"question": "When is my next flight?"},
)

reply = agent.poll_queued_reply(
    queued.request_id,
    queued.reply_private_key,
    wait_seconds=60,
)
```

See [Offline queue](https://docs.fau.run/developer/connect/offline-queue.md) and
[Outstanding requests](https://docs.fau.run/developer/connect/outstanding-requests.md).

## What the SDK owns vs the protocol

| Concern | SDK | Still your job |
| - | - | - |
| Resolve + MCP session | Yes | Host JWKS or enroll |
| RFC 9421 signing | Yes | Protect the private key |
| `approval_required` wait/retry helpers | Yes | Show domain + match code in product UI |
| Offline seal / poll | Yes | Durable storage of reply keys across restarts |
| Tool choice / product copy | No | Prefer structured tools; never ask for Gmail OAuth |

Wire truth remains [Wire specification](https://docs.fau.run/developer/protocol/spec.md). If the SDK and the spec
disagree, the **spec** wins — file a bug against `sdk/python`.

## Next

* [Approvals](https://docs.fau.run/developer/tools/approvals.md) — match codes and retry rules
* [Tools](https://docs.fau.run/developer/tools/overview.md) — what to call
* [Integration checklist](https://docs.fau.run/developer/reference/checklist.md) — before production


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.