Install and configure the AgentRail Python SDK client

The AgentRail Python SDK (agentrail) is an async HTTP client for the Task Lifecycle API. It requires Python 3.10 or newer, uses httpx for transport, and exposes Pydantic v2 models for all request and response types.

Install from PyPI

pip install agentrail

Install from the local repository

If you need to work against the SDK before a package release, install it in editable mode from the repository source:

pip install -e /path/to/agentrail/sdk/python

Editable installs (-e) reflect changes to the source immediately without reinstalling.

Use as an async context manager

The Python client manages an httpx.AsyncClient internally. Use it as an async context manager to ensure the connection pool is closed when your code finishes:

import asyncio
import os

from agentrail import AgentRailClient

async def main():
    async with AgentRailClient(
        base_url=os.getenv("AGENTRAIL_BASE_URL", "http://127.0.0.1:3000"),
        api_key=os.environ["AGENTRAIL_API_KEY"],
    ) as client:
        # Use client here
        ...

asyncio.run(main())

If you need the client to outlive a single async with block, you can call await client.close() manually instead.

Model conventions

Python models expose snake_case attributes. All response models are validated Pydantic v2 objects. Request models also accept the API’s camelCase aliases, but prefer snake_case in Python code.

Next steps

Configure authentication — set up your API key and base URL
Client methods — list tasks, submit work, and ship
Stream events — subscribe to real-time task lifecycle events
Verify webhooks — validate inbound webhook deliveries

Verify incoming AgentRail webhook events in TypeScript

AgentRailClient task lifecycle methods — Python SDK

​Install from PyPI

​Install from the local repository

​Use as an async context manager

​Model conventions

​Next steps

Install from PyPI

Install from the local repository

Use as an async context manager

Model conventions

Next steps