Agent Assembly Python SDK

Python SDK for AI Agent Assembly — a governance-native runtime for AI agents. One init_assembly() call wires your agent into the policy gateway and applies pre-execution allow/deny on tool calls, without changing how the agent itself is written.

The SDK hands records to the runtime; it does not give you an audit trail. The framework adapters offer a governed call's outcome to an audit hook on the governance interceptor, and over a connected runtime that hook writes it to the native event channel — the same one agent registration uses. That is a handoff, not evidence: the send is unacknowledged, so this SDK cannot tell you the record arrived, and does not claim it did. Downstream, AAASM-5783 is open on report_event payloads reaching neither the live stream nor the durable entry — until it lands, no SDK can claim ADR 0033 §6 Observed. Without a reachable runtime there is no channel at all and nothing is emitted.

Denied calls are covered too. The eleven governing adapters build a record on the denied path as well as the allowed one, marked so a reader can tell a blocked call from a tool that ran and returned the denial text (AAASM-5787); eight of them used to return or raise before their record helper. langgraph instruments nodes for lineage and has no tool-call gate, so it records neither. Enforcement is unaffected either way: a policy DENY still blocks the tool. init_assembly() warns when no record can be sent and reports audit_sink on the returned context (AAASM-5750).

Why use it

• Framework adapters for LangChain, LangGraph, CrewAI, OpenAI Agents, Pydantic AI, Google ADK, Haystack, Smolagents, Agno, LlamaIndex, Microsoft Agent Framework, and MCP servers — drop in, no SDK rewrites required.
• Pre-execution policy enforcement via the FrameworkAdapter ABC — block disallowed tool calls before they hit the LLM.
• Agent lineage — parent / root / team identity is registered with the gateway and carried on every policy check. (An audit trail from this SDK layer depends on a reachable runtime — see the note above.)
• Native PyO3 fast path (optional) — drop into a Rust runtime client when you need sub-millisecond policy checks.
• Typed throughout — Pydantic models for every gateway payload, mypy strict on adapter base and registry.

Framework compatibility

The SDK governs these AI-agent frameworks; install whichever one your agent already uses alongside agent-assembly and the matching adapter activates automatically (the frameworks are not runtime dependencies of the SDK — you pin the framework, within the supported range). Tested version is the exact line exercised by the live smoke suite (AAASM-3525) and the integration tests; older releases within the supported range are expected to work but are not continuously tested.

Python framework compatibility is documented authoritatively in the SDK docs — Framework compatibility — because the Python adapters and the ranges they advertise via get_supported_versions() are the source of truth (Python-specific detail, version-sync policy, and the Pydantic AI hook-point note live there). The core docs provide a cross-SDK index/hub that links out to each SDK's own page (Python here, plus Node and Go) — an index, not the canonical matrix (a /stable/ link — it 404s until the first GA release, by design).

Project status

Pre-1.0 (0.x) — published and usable, API not yet frozen. The SDK is released to PyPI from the 0.0.x line (the version badge above reflects the current release). Until 1.0.0, minor versions may introduce breaking changes to the public surface; pin an exact version (agent-assembly==0.0.x) if you need a stable contract.

• Releases — PyPI release history · GitHub releases
• Changelog — tracked via commits to master until the first tagged 1.0 release; see the release notes page.
• Stability — the init_assembly() entry point and the exception hierarchy are the most stable surface; framework adapters and the native fast path may evolve faster.

Requirements

• Python >=3.12,<4.0 (3.12, 3.13, 3.14 are tested in CI)
• Rust toolchain (stable channel) — only required for building the optional native extension via maturin develop. Pure-Python users do not need Rust.
• uv ≥ 0.4 — recommended for managing the dev environment. (pip works for plain installs.)

Installation

Use the SDK in your project

The package is published on PyPI as agent-assembly:

pip install --pre agent-assembly            # pure-Python SDK
pip install --pre 'agent-assembly[runtime]' # SDK + bundled aasm runtime binary (platform wheel)

--pre is required for now. Agent Assembly is currently published only as a pre-release on PyPI, and pip skips pre-releases unless you pass --pre. Drop the flag once a stable (non-pre-release) version is published.

agent-assembly[runtime] pulls a platform wheel (manylinux, macosx) that bundles the aasm sidecar binary, so you don't need a separate runtime install. Plain agent-assembly is the pure-Python client and expects an aasm runtime to be reachable some other way.

Confirm the aasm CLI is on your PATH:

aasm --version   # e.g. aasm 0.0.1rc6

Supply-chain verification. The only official PyPI package is agent-assembly (anything else is a typosquat). Every release ships PEP 740 attestations on its PyPI files page and a CycloneDX SBOM attached to its GitHub Release. See SECURITY.md for how to verify what you installed.

With uv:

uv add --prerelease=allow agent-assembly

--prerelease=allow is required for now. Unlike pip, uv refuses to resolve pre-releases unless you opt in. Agent Assembly is currently published only as a pre-release on PyPI, so uv add agent-assembly fails to resolve without it. Drop the flag once a stable (non-pre-release) version is published.

To track unreleased changes, install from the main branch:

pip install git+https://github.com/ai-agent-assembly/python-sdk.git

Develop on the SDK

Clone the repo and sync the dev environment with uv:

git clone https://github.com/ai-agent-assembly/python-sdk.git
cd python-sdk
uv sync

To build the optional PyO3 extension locally (requires Rust):

uv tool run maturin develop --manifest-path native/aa-ffi-python/Cargo.toml --release

The pure-Python SDK works without the native extension — maturin develop is only needed if you want the sub-millisecond RuntimeClient fast path.

Quick Start

A governed LangChain ReAct agent that runs offline against a mock LLM. The example imports LangChain in addition to the SDK, so install both:

pip install --pre agent-assembly langchain langchain-classic langchain-community

from langchain_classic.agents import AgentExecutor, create_react_agent
from langchain_classic.tools import Tool
from langchain_community.llms import FakeListLLM
from langchain_core.prompts import PromptTemplate

from agent_assembly import init_assembly

with init_assembly(
    gateway_url="http://localhost:7391",
    api_key="dev-key",
    agent_id="quickstart-agent",
    mode="sdk-only",
):
    llm = FakeListLLM(responses=[
        "Thought: I should look up the user.\nAction: whoami\nAction Input: alice\n",
        "Thought: I have the answer.\nFinal Answer: alice is in engineering\n",
    ])
    tools = [Tool(name="whoami", func=lambda name: f"{name} is in engineering", description="who")]
    prompt = PromptTemplate.from_template(
        "Use the tools.\n{tools}\nTool names: {tool_names}\nQ: {input}\n{agent_scratchpad}"
    )
    executor = AgentExecutor(agent=create_react_agent(llm, tools, prompt), tools=tools, max_iterations=2)
    print(executor.invoke({"input": "Which team is alice on?"})["output"])

What this does:

1. init_assembly() registers the agent with the gateway and auto-loads the LangChain adapter — each tool call the wrapped agent makes from now on goes through the policy gate.
2. The FakeListLLM replays canned responses so the example runs offline with no real LLM.
3. The with block tears down the gateway connection and unwinds adapter hooks on exit.

Public API

• init_assembly(gateway_url, api_key, agent_id=None, mode="auto", *, control_plane_url=None, allow_insecure=False) -> AssemblyContext
• Exceptions: AssemblyError, AgentError, PolicyError, GatewayError, ConfigurationError
• Data models: AgentConfig, AgentState, PolicyEvaluation

Agent registration and the pre-execution policy check are not REST calls: the SDK goes through the native aa-sdk-client shim to the core over gRPC/UDS (ADR 0004) — it never calls a core HTTP endpoint directly for those. init_assembly registers the agent on startup, and a tool call is checked via the native query_policy so a deny blocks it before the tool runs.

Control-plane routing

By default the SDK issues its remaining HTTP routes (topology edges, secret dispatch) against gateway_url — the single-host OSS dev setup. Pass control_plane_url to route those HTTP calls to a separate control-plane host while gateway_url continues to serve the gRPC data path:

init_assembly(
    gateway_url="http://gateway:7391",
    control_plane_url="http://control-plane:9000",
    api_key="dev-key",
)

Both URLs also resolve from the environment when their kwargs are omitted. Resolution order is explicit kwarg > env-var > unset:

Insecure transport opt-in

Agent registration dials the gateway's gRPC port over the native register call. By default a plaintext http:// register channel to a non-loopback host is refused — the Register call carries the agent identity, so it must not travel unencrypted to a remote host. Loopback (local dev) and https:// targets always pass.

Pass allow_insecure=True to opt into plaintext to a non-loopback host, on a trusted network only (e.g. a private link where TLS terminates elsewhere). This mirrors the operator-control connect(allow_insecure=...) opt-in:

init_assembly(
    gateway_url="http://gateway.internal:7391",
    allow_insecure=True,  # trusted-network only; leave False in production
)

Error Handling

from agent_assembly import init_assembly
from agent_assembly.exceptions import ConfigurationError

try:
    # An invalid mode fails validation up front and raises ConfigurationError.
    # (An empty/unset gateway_url is not an error — it triggers local
    # auto-discovery; a gateway that can't be reached raises GatewayError.)
    context = init_assembly(gateway_url="http://localhost:7391", mode="invalid-mode")
except ConfigurationError as exc:
    print(f"Invalid configuration: {exc}")

Auto-discovery caveat. Local auto-discovery tries to auto-start a gateway via the aasm CLI. If aasm is not on your PATH, discovery can't start one and raises ConfigurationError immediately (rather than the GatewayError you'd get after the ~5 s health-check timeout when aasm is present but the gateway never becomes ready). Install the runtime with pip install --pre 'agent-assembly[runtime]'.

Development

Run tests:

uv run pytest

Run integration tests:

uv run pytest -m integration

Lint and type-check:

uv run ruff check .
uv run mypy agent_assembly

Native Core Extension

Build and install the PyO3 extension locally:

uv tool run maturin develop --manifest-path native/aa-ffi-python/Cargo.toml --release

Validate native module import:

from agent_assembly._core import RuntimeClient, GovernanceEvent

Run opt-in native integration tests:

AAASM_RUN_NATIVE_CORE_TESTS=1 uv run pytest test/integration/test_native_core_runtime.py
AAASM_RUN_MATURIN_TESTS=1 uv run pytest test/integration/test_native_core_maturin.py

Documentation

• Project docs (rendered) — https://docs.agent-assembly.com/python-sdk/ (versioned via mike; pick latest or stable from the version selector)
• Quick Start — source — install and govern your first agent in five minutes (offline LangChain example).
• Core Concepts — source — the adapter pattern, native FFI vs. pure-Python, the init_assembly() lifecycle, and modes/enforcement. Deep dive in Architecture.
• Guides — Framework examples, Handling allow/deny decisions, Type checking.
• Configuration — source — gateway URL / API-key resolution, runtime modes, enforcement modes.
• API reference — rendered / source — auto-generated from package docstrings via mkdocstrings. Per-module pages: Client, Exceptions, Models.
• Compatibility & Versioning — source — Python versions, core-runtime tracking, release process, and ADRs.
• Troubleshooting — source — common integration errors and fixes.

Ecosystem

This SDK is one piece of the AI Agent Assembly project. Start from the organization profile to discover every repo, or jump directly:

The protocol specification and gateway behaviour the SDK targets live in the core runtime monorepo; see its README for the spec and architecture. For how this SDK stays in sync with the core runtime, see the Compatibility & Versioning docs.

Contributing

Please read CONTRIBUTING.md before opening a PR — it covers dev environment setup, framework adapter authoring, the test/lint command list, branch naming, and the PR checklist.

Support

• Bugs & feature requests — open a GitHub issue.
• Questions & usage help — start with the documentation site and the Troubleshooting guide, then open an issue if you're still stuck.
• Security — please do not file public issues for vulnerabilities. Report them privately via GitHub Security Advisories.

License

MIT License