AgentDynamics

APM for AI agents. AgentDynamics does for agents what AppDynamics does for services. It shows how your agents work through tasks, what each step costs, where flows loop, stall or fail, and whether the agent's process is any good.

• Works with what you already have: LangGraph, LangChain, the OpenAI Agents SDK, the Anthropic and OpenAI SDKs, CrewAI, LlamaIndex, anything that speaks OpenTelemetry, LangSmith, Langfuse, log pipelines and Claude Code.
• Zero dependencies: one pip install, one process, runs on a laptop or in Kubernetes.
• Self-hosted: your prompts and traces never leave your network.

Quickstart (2 minutes)

pip install agentdynamics
agentdynamics serve --open          # console at http://127.0.0.1:8787

Then connect your agent with one of these options. Pick the first one that matches how your agent is built.

1. Python: one line

import agentdynamics
agentdynamics.init()      # auto-instruments Anthropic, OpenAI, LangChain/LangGraph and OpenTelemetry

Every model call is now tracked, with tokens, cost, latency, truncations and errors. To group calls into tasks and see your agent's flow, add a decorator and name the stages:

@agentdynamics.trace                     # one call = one task in the console
def handle_ticket(question):
    with agentdynamics.span("plan"):     # stages become nodes in the workflow graph
        plan = client.messages.create(...)
    with agentdynamics.span("act"):
        lookup_order(order_id)           # decorate tools with @agentdynamics.tool
    if escalated:
        agentdynamics.outcome("failed", reason="customer escalated")   # state it, don't let it be guessed
    ...

Without outcome(), success is inferred from errors, interrupts and follow-ups. The console always shows which outcomes were stated and which were guessed; grades can also be posted afterwards by a person or an eval pipeline (POST /api/outcomes), or by your own systems using your own ids: trace with agentdynamics.trace("support", ticket_id="T-123") and post {"key": {"ticket_id": "T-123"}, "outcome": "rework"} when the ticket is reopened.

2. Python, zero code changes

agentdynamics run python app.py         # like ddtrace-run / opentelemetry-instrument

3. LangGraph / LangChain (Python or JS): environment variables only

export LANGSMITH_TRACING=true
export LANGSMITH_ENDPOINT=http://127.0.0.1:8787/langsmith

AgentDynamics speaks the LangSmith ingestion API, so graphs, nodes, threads and feedback arrive unchanged.

4. Any OpenTelemetry app (OpenAI Agents SDK, CrewAI, LlamaIndex, Vercel AI SDK, Java/Go/.NET)

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://127.0.0.1:8787/v1/traces

GenAI semantic conventions, OpenInference and OpenLLMetry are all understood, over protobuf or JSON.

5. Already using LangSmith or Langfuse? Don't change anything

agentdynamics connect langsmith         # prints the 4-line config to pull runs from your existing project

6. Anything else

agentdynamics connect http prints a single curl call. agentdynamics connect logs shows how to point Fluent Bit or Vector at AgentDynamics.

Check it works

agentdynamics doctor                    # checks URL + key, sends a test trace, confirms it shows up

The console's Get started page shows the same snippets and turns green when your first trace arrives.

What it looks like

The Flow Map: where work goes, what each hop costs, and what is failing. Red edges are errors.

The Overview: cost, Apdex and flow health against baselines learned from your own history.

Governance: what Aegis refused, which rule refused it, and which grants are never used.

Reproduce these locally from synthetic traffic, no API keys needed:

agentdynamics --data .demo-data --claude-root "" serve --port 8790 &
LANGSMITH_ENDPOINT=http://127.0.0.1:8790/langsmith python examples/langgraph_style_app.py 70
python examples/otel_multiagent.py 45 http://127.0.0.1:8790
AGENTDYNAMICS_URL=http://127.0.0.1:8790 python examples/governed_agent.py 40

What you get

The full metric catalog is in docs/METRICS.md.

Governance with Aegis

Aegis decides what an agent may do. AgentDynamics shows what it did. Connecting them takes one call:

from agentdynamics.integrations import aegis as governance
governance.instrument(kernel, root, watchdog=governance.Watchdog(max_repeated_denials=3))

That call sets up four flows:

1. Every Aegis decision appears in its task. Denials carry the rule id, and the Aegis audit log carries the task's run id so the two logs join.
2. Model calls are charged to the Aegis budget before they're sent. When the budget runs out, the call is refused and never made.
3. A watchdog revokes the grant of an agent that keeps probing a boundary, for example after a prompt injection, and tripwires (decoy tools and planted canary values) stop a run before the call that touches one is made. For tools that can't be undone, an opt-in reviewer model checks each call against what the user asked before Aegis admits it, and refuses what goes beyond it (review={"tools": ["payments.refund"]}).
4. agentdynamics policy export writes a tighter, least-privilege policy from observed behaviour. aegis ratify and aegis drift verify its declaration; agentdynamics policy check replays the traffic that actually ran through it and reports how much it would refuse, so a policy change can be gated in CI.

The console's Governance page shows denials, budget stops, revocations, unused grants and budget headroom per policy version. See docs/GOVERNANCE.md.

Python API

Environment variables:

Telemetry is sent from a background thread with a bounded queue. Your agent never waits on it and never fails because of it.

Running it for a team

agentdynamics keys create --role ingest     # for apps / collectors
agentdynamics keys create --role read       # for people and Grafana
agentdynamics keys create --role admin      # for rules, SLOs and config
agentdynamics keys create --role read --project checkout    # one team: sees and sends only its projects
docker compose -f deploy/docker-compose.yml up -d   # AgentDynamics + OpenTelemetry Collector gateway

The store is a SQLite file by default. For several instances behind a load balancer, or a database you back up and operate like any other, use Postgres: pip install "agentdynamics[postgres]" and set AGENTDYNAMICS_DB_URL=postgresql://... (or deploy/docker-compose.postgres.yml). One instance is elected to write the analysis; the others serve the console and take ingest, and one takes over if the writer goes away. An existing install moves with its history: agentdynamics store copy --to postgresql://..., then agentdynamics store verify.

• Security: role-based API keys, optionally scoped to projects. A scoped key reads only its projects' tasks, runs, steps and events, on every endpoint, and can't write into or over another project's traces.
• Privacy: redaction of emails, API keys and card numbers, or store_content = false to keep metadata only.
• Operations: retention, Prometheus /metrics, /healthz, a status page for every source, and alerts to Slack, PagerDuty or any webhook: health-rule events and SLO burn-rate pages, delivered in order with retries (agentdynamics alerts test checks a destination end to end).

See deploy/ and docs/ARCHITECTURE.md.

Development

pip install -e ".[test,toml]" && pip install "aegis-kernel>=0.4.0"
python -m unittest discover tests   # real LangSmith/Anthropic/OpenAI SDKs, Aegis kernel, OTLP protobuf, pull connectors

Demo traffic is under What it looks like above. CLAUDE.md has the architecture and the invariants to work within; ROADMAP.md is what is planned and what is deliberately not.

License

Apache 2.0. See LICENSE.