AG2 Production Guide
Running AG2 1.x in production — pinning, testing with TestConfig, durable hubs, serving over A2A, observability, security and scaling.
Verified against
ag21.3.2 (checked 2026-11-19).
Pin the right distribution
Section titled “Pin the right distribution”ag2 changed API completely at 1.0. Pin a range that matches the code you wrote:
# requirements.txt — AG2 1.x code (import ag2)ag2[openai,mcp]>=1.3.2,<2
# AG2 Classic code (import autogen) — maintenance mode# autogen[openai]Never leave ag2 unpinned in a Classic codebase: a fresh install would pull 1.x and every import autogen would fail. Running Classic in production is covered in the AG2 Classic production guide.
Test without a model
Section titled “Test without a model”Use ag2.testing.TestConfig to script model outputs (strings and ToolCallEvents). Tests then exercise your tools, schemas and control flow deterministically and offline — see Testing. Keep a small separate suite that hits the real provider, run on a schedule rather than on every commit.
Deployment
Section titled “Deployment”Container
Section titled “Container”FROM python:3.12-slimWORKDIR /appCOPY requirements.txt .RUN pip install --no-cache-dir -r requirements.txtCOPY . .CMD ["python", "-m", "app"]Serving an agent
Section titled “Serving an agent”- A2A —
A2AServer(agent).build_jsonrpc(...)returns an ASGI app; run it under uvicorn or any ASGI server. REST and gRPC transports can share onetask_store=. Since 1.2.0A2AServercan run on several replicas: pass a versioned shared task store together with anevent_stream=that carries task events between replicas (see the upstream A2A server docs). - MCP —
ag2.mcp.MCPServer(agent)exposes anAgentas an MCP server:await server.run_stdio()for a subprocess client, or run the server object itself under uvicorn for streamable HTTP at/mcp. See Serving an agent as an MCP server. - AG-UI / ACP — adapters in
ag2.ag_uiandag2.acp(extrasag-ui,acp) connect agents to front-ends and editor clients (see ACP: coding agents and editors).
State and durability
Section titled “State and durability”- A Network
Hubpersists its registry and write-ahead log through aKnowledgeStore.MemoryKnowledgeStoreis for tests; useDiskKnowledgeStore,SqliteKnowledgeStoreorRedisKnowledgeStore(extraredis) in production so channels can be restored withHub.hydrate()after a restart. TransitionGraphs are plain data (to_dict()), so workflow channels survive restarts without re-registering Python callables.- For long single-agent sessions, add
plugins=[KnowledgePlugin(store=..., ...)]with a compaction strategy (TailWindowCompactorSummarizeCompactfromag2.compact) to cap history growth. See Knowledge, memory and compaction.
Resilience
Section titled “Resilience”- Provider configs accept
timeout=andmax_retries=(OpenAI-family) — set both explicitly. - A tool that raises does not fail
ask(). AG2 publishes aToolErrorEventand hands it to the model as the tool result, and that text includes the Python traceback. So catch expected failures inside the tool and return a short message the model can act on, and keep secrets out of exception messages.ag2.testing.TestConfigbehaves differently by default: it re-raises the tool’s exception so a test fails loudly. Passraise_tool_errors=Falseto model what a real provider does. - Bound multi-agent runs:
TransitionGraph(..., max_turns=N)for workflows, and an explicitclose()plus a timeout forconversationanddiscussionchannels, which never end on their own. - A2A clients reconnect on dropped streams (
max_reconnects,reconnect_backoffonA2AConfig) and raiseag2.a2a.errors.A2AReconnectErrorwhen the budget is spent.
Security
Section titled “Security”- Code execution: run model-written code through
SandboxCodeTool/SandboxShellToolwith aDockerEnvironmentorDaytonaEnvironment.LocalEnvironmentis a plain subprocess with no isolation, so keep it for trusted code.CodeExecutionToolandShellToolrun in the model provider’s sandbox, not on your infrastructure; check that this is acceptable for your data. See Code execution. - MCP — restrict exposed tools with
allowed_tools=/blocked_tools=; preferMCPToolkit(client-side) when credentials must stay inside your infrastructure. - A2A push notifications — if you enable them (
push_config_store=), passpush_url_validator=(for examplea2a.utils.push_url_validator.validate_push_notification_url, which allows only public http(s) hosts) so client-supplied webhook URLs cannot reach internal addresses (SSRF); available since 1.2.0.validate_input_modes=Truerejects message parts whose media type the card does not declare. Sign agent cards withcard_signer=where clients need to verify them; clients check withcard_signature_verifier=onA2AConfig. - Keys — config classes read provider keys from the environment; keep them in a secrets manager, not in code.
Observability
Section titled “Observability”TelemetryMiddleware (extra tracing) emits OpenTelemetry spans for agent turns, LLM calls, tool executions and human input, following the GenAI semantic conventions. Each reply carries a usage report:
import asyncio
from opentelemetry.sdk.resources import Resourcefrom opentelemetry.sdk.trace import TracerProviderfrom opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from ag2 import Agentfrom ag2.config import OpenAIConfigfrom ag2.middleware import TelemetryMiddleware
provider = TracerProvider(resource=Resource.create({"service.name": "support-bot"}))provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter())) # use an OTLP exporter in production
agent = Agent( "support", prompt="You answer support questions.", config=OpenAIConfig(model="gpt-6-luna"), middleware=[TelemetryMiddleware(tracer_provider=provider, capture_content=False)],)
async def main() -> None: reply = await agent.ask("How do I reset my password?") report = await reply.usage() # ag2.usage.UsageReport for the whole run print(report.total, dict(report.by_model))
asyncio.run(main())capture_content=Falsekeeps prompts, completions and tool arguments out of spans. The default (True) records them.- Subscribe to typed events on a
MemoryStream(tool calls, model responses, human-input requests, compaction) for audit logs and UIs. observers=[TokenMonitor(...), LoopDetector(...)]alert on runaway token use and repeated tool calls.MetricsMiddleware(extrametrics) exports metrics. See Middleware and observers.- The Hub’s audit trail records agent registration, channel lifecycle and expectation violations.
Scaling
Section titled “Scaling”- Agents are cheap async objects; run many concurrent
ask()calls in one process before reaching for more processes. - For horizontal scale, put stateless agent services behind a load balancer and keep conversation state in the hub’s store or your own database.
- Watch token usage per run (
await reply.usage()) and set provider-side budgets.