Troubleshooting
This page is a starting point when something is not working the way the docs describe. It is for operators and developers who have already read the Docker Compose quickstart or an SDK page and hit a specific problem.
Because AI Agent Assembly is composed of five independently versioned programs (core, three SDKs, and Arena), most concrete runtime symptoms are covered in the owning component’s own troubleshooting section. This page routes you to the right one and lists cross-cutting issues that don’t belong to a single component.
Common first-run failures
If you are evaluating AI Agent Assembly for the first time, these are the symptoms newcomers hit most often — each with the exact fix. If your symptom isn’t here, use the component routing table further down.
| Symptom you see | Cause | Fix |
|---|---|---|
pip install agent-assembly → ERROR: Could not find a version that satisfies the requirement agent-assembly / No matching distribution found | Only pre-release versions are published on PyPI right now; pip skips pre-releases by default. | Install with the --pre flag: pip install --pre agent-assembly. |
| On Python 3.13 / 3.14, agent registration appears to do nothing — no events reach the gateway | Older SDK builds had no wheels for CPython 3.13/3.14, so the native extension silently fell back to a no-op. | Upgrade to rc.4 or later, which ships cp313 and cp314 wheels: pip install --pre --upgrade agent-assembly. Confirm your interpreter with python --version. |
| SDK cannot reach the gateway even though a gateway is running | Connecting to the wrong port/protocol — the SDKs speak gRPC on 50051, while the gateway’s REST/OpenAPI control-plane surface (used by the dashboard, and what AA_GATEWAY_URL points at) is HTTP on 7391. Port 8080 is a different endpoint — the aa-runtime health/metrics server (AA_METRICS_ADDR) — not the gateway REST API. | Point the SDK at the gRPC endpoint (50051), not the REST port (7391) or the metrics port (8080). For a fully local loop with no external gateway, run one yourself: aasm start brings up a local gateway the SDK can register against. |
aa-runtime logs policy file not found — starting without enforcement | Neither AA_POLICY_PATH (local enforcement) nor AA_GATEWAY_ENDPOINT (delegate to a gateway) is set on the runtime container, so it has no policy source at all — every governed call is allowed by default (AAASM-4988). | Set one of the two on the aa-runtime service: AA_GATEWAY_ENDPOINT to delegate per-tool decisions to a real aa-gateway (see the governed topology), or AA_POLICY_PATH for the runtime’s own coarse, action-type local policy. |
ImportError / ModuleNotFoundError for AgentExecutor or create_react_agent when running a LangChain example | Recent LangChain moved these legacy agent constructors out of the top-level langchain package into the langchain_classic package. | Import from the new location: from langchain_classic.agents import AgentExecutor, create_react_agent (and pip install langchain-classic if it isn’t already present). |
Where component-specific troubleshooting lives
| Symptom | Look here |
|---|---|
| SDK cannot register the agent / handshake fails | Python SDK docs, Node SDK docs, Go SDK docs |
Sidecar proxy (aa-proxy) drops connections | Core docs — Proxy section |
eBPF sensor (aa-ebpf) fails to load | Core docs — eBPF section |
| Policy YAML rejected at gateway | Policy reference |
| Compatibility mismatch between core and an SDK | Compatibility matrix |
Cross-cutting checks
Before opening an issue, verify:
- The SDK version matches a supported core version — see the Compatibility matrix.
- The API key is set in the environment (
AA_API_KEY) — an unset credential is the most common cause of “agent registration failed”. - The gateway URL is reachable from the host running the agent
(
AA_GATEWAY_URL, defaulting tohttp://localhost:7391, a local gateway auto-started viaaasm startif none is already running).
Still stuck? Open an issue
If none of the routes above resolve the problem, open a GitHub issue on the owning repository — the core team monitors each repo’s issue tracker and routes docs bugs back here.
Include the SDK version, core version, and a minimal reproducer. Docs bugs can be filed on this repo's tracker instead.
Last reviewed: 2026-07-17 — AI Agent Assembly Team
Last updated: 2026-09-07 by AI Agent Assembly Team