agentweave-sdk

AgentWeave

Agent runtime observability and provenance layer for multi-agent AI systems.

When agents delegate, loop, and fanout across tools and models, the final output tells you nothing. AgentWeave makes the decision chain the first-class artifact — every span carries W3C PROV-O provenance on OpenTelemetry: which agent acted, which model ran, what was consumed, what was generated, and how much it cost.

Three paths to instrumentation: decorators, auto-instrumentation, or zero-code proxy. Any OTLP backend.

agent.nix                          94ms
├── llm.claude-sonnet-4-6          81ms  ← prompt_tokens=847, completion_tokens=312
├── tool.delegate_to_max           312ms
│   └── agent.max                  298ms
│       ├── llm.gemini-2.0-flash   187ms ← prompt_tokens=1203, completion_tokens=89
│       └── tool.web_search         94ms
├── llm.claude-sonnet-4-6          80ms  ← found it
└── tool.deploy_portfolio           48ms

How it works

graph LR
    subgraph Agents["Agents — proxy mode"]
        A1["Anthropic Agent"]
        A2["Gemini Agent"]
        A3["OpenAI Agent"]
    end

    SDK["Any Agent — SDK decorators / auto_instrument()"]

    subgraph Proxy["AgentWeave Proxy :4000"]
        P["Multi-Provider Proxy"]
    end

    subgraph LLMs["Upstream LLMs"]
        AN[api.anthropic.com]
        GO[generativelanguage.googleapis.com]
        OA[api.openai.com]
    end

    subgraph Observability
        OT["OTLP Collector — Tempo / Jaeger / Langfuse"]
        GR["AgentWeave Dashboard"]
    end

    A1 -- "ANTHROPIC_BASE_URL" --> P
    A2 -- "GOOGLE_GENAI_BASE_URL" --> P
    A3 -- "OPENAI_BASE_URL" --> P
    SDK -- "OTel spans" --> OT

    P -- "/v1/messages" --> AN
    P -- "/v1beta/models/*" --> GO
    P -- "/v1/chat/completions" --> OA
    P -- "OTel spans" --> OT
    OT --> GR

Three paths to instrumentation:

1. Auto-instrumentation (auto_instrument()) — one call patches Anthropic and OpenAI SDKs. No decorators needed.
2. Decorators (@trace_agent, @trace_llm, @trace_tool) — wrap your functions directly in Python, TypeScript, or Go. Zero infrastructure needed.
3. Proxy — point any agent's base URL at AgentWeave. It auto-detects the provider, forwards upstream, extracts token counts, and emits OTel spans. No code changes.

Screenshots

Main dashboard overview (KPIs, latency, token/cost trends, and agent/model breakdowns)

Session explorer view

Routing view

Replay / debug view

Grafana / Tempo trace view

How AgentWeave fits in the ecosystem

Tools like OpenLIT, Langfuse, and LangSmith are good at answering: what did my LLM do? Token counts, latency, cost per request, prompt logging. If you have a single agent or a single app making LLM calls, those tools cover the problem well.

AgentWeave answers a different question: what did my agent system do?

When one agent delegates to another across different machines, frameworks, or providers, you lose the thread. A trace that stops at the process boundary tells you nothing about why the overall task failed, which agent introduced the bad output, or where the cost actually went.

The intended use: run OpenLIT or Langfuse inside each agent for deep per-agent observability, and point them all at AgentWeave for the system view above that. The delegation graph, cross-agent cost rollups, and traces that span process boundaries are what AgentWeave adds.

No cloud, no SaaS, no enterprise tier. Just the tool.

Install

AgentWeave is in developer preview. Start with a local proxy and a local OTLP collector; private dogfood deployments live in runbooks, not in the public quickstart.

Local proxy path

pip install "agentweave-sdk[proxy]"
agentweave proxy start --port 4000 --endpoint http://localhost:4318
export ANTHROPIC_BASE_URL=http://localhost:4000/v1

Use your normal provider API key in the client environment. Proxy-side key injection and private NodePort URLs are dogfood-only conveniences, not required for the public developer-preview path.

Quickstart (Python)

Option A — Auto-instrumentation (zero decorators)

from agentweave import auto_instrument

auto_instrument()  # patches Anthropic + OpenAI SDKs automatically

# Every client.messages.create() and client.chat.completions.create()
# now emits OTel spans with token counts — no wrappers needed.

Option B — Decorators (explicit control)

from agentweave import AgentWeaveConfig, trace_agent, trace_llm, trace_tool

AgentWeaveConfig.setup(
    agent_id="my-agent-v1",
    agent_model="claude-sonnet-4-6",
    otel_endpoint="http://localhost:4318",
)

@trace_llm(provider="anthropic", model="claude-sonnet-4-6",
           captures_input=True, captures_output=True)
def call_claude(messages: list) -> ...:
    return client.messages.create(...)

@trace_tool(name="web_search", captures_input=True, captures_output=True)
def web_search(query: str) -> str:
    ...

@trace_agent(name="my-agent")
async def handle(message: str) -> str:
    response = call_claude(messages=[{"role": "user", "content": message}])
    return web_search(response.content[0].text)

All three spans link to the same trace ID. Open any OTLP backend and you see the waterfall.

Framework Examples

Auto-Instrumentation

Patch LLM SDK client methods with a single call — no decorators needed.

from agentweave import auto_instrument, uninstrument

auto_instrument()                              # patch all detected SDKs
auto_instrument(providers=["anthropic"])        # selective
auto_instrument(captures_output=True)          # include response preview

uninstrument()                                 # restore originals

• Supports Anthropic (Messages.create) and OpenAI (Completions.create), sync + async
• Composes with explicit @trace_llm — auto-instrumentation detects existing spans and skips to avoid double-tracing
• Idempotent — calling auto_instrument() twice is safe
• Streaming support deferred to a follow-up

Decorators

@trace_agent

Root span for an agent turn. Nests all downstream tool and LLM calls.

@trace_agent(name="nix")
def handle(message: str) -> str: ...

Session grouping

Pass session_id to group all spans from a single user conversation together. The value is attached as session.id on every span, making it a filterable dimension in Grafana / Tempo.

@trace_agent(name="nix", session_id="conv-abc123")
def handle(message: str) -> str: ...

The proxy also accepts the X-AgentWeave-Session-Id header for zero-code session tagging — see docs/session-grouping.md.

@trace_tool

Span for any tool call — file ops, API calls, shell commands, A2A delegation.

@trace_tool(name="delegate_to_max", captures_input=True, captures_output=True)
def delegate_to_max(task: str) -> dict: ...

@trace_llm

Span for LLM invocations. Auto-extracts token counts and stop reason from Anthropic, OpenAI, and Google Gemini response shapes.

@trace_llm(provider="anthropic", model="claude-sonnet-4-6", captures_output=True)
def call_claude(messages: list) -> anthropic.Message: ...

Captured automatically:

• prov.llm.prompt_tokens / prov.llm.completion_tokens / prov.llm.total_tokens
• prov.llm.stop_reason
• prov.llm.response_preview (first 512 chars, when captures_output=True)

Sub-agent Attribution

When agents delegate to sub-agents, use the sub-agent attribution parameters to link child sessions to their parent and distinguish agent roles in traces.

Python SDK

# Main agent — tags itself as the root session
@trace_agent(name="nix", session_id="sess-main-123", agent_type="main", turn_depth=1)
def main_agent(msg: str) -> str:
    return delegate_to_sub(msg)

# Sub-agent — linked to parent session
@trace_agent(name="max", parent_session_id="sess-main-123",
             agent_type="subagent", turn_depth=2)
def sub_agent(task: str) -> str:
    return call_llm(task)

Environment variable auto-detection

Set AGENTWEAVE_PARENT_SESSION_ID and the SDK auto-populates prov.parent.session.id, defaults agent_type to "subagent", and turn_depth to 2:

export AGENTWEAVE_PARENT_SESSION_ID=sess-main-123

Proxy headers

When using the proxy, pass sub-agent context via HTTP headers:

TypeScript SDK

import { traceAgent } from 'agentweave-sdk';

const subAgent = traceAgent({
  name: 'max',
  parentSessionId: 'sess-main-123',
  agentType: 'subagent',
  turnDepth: 2,
})(async (task: string) => {
  return callLlm(task);
});

New span attributes

PROV-O Attributes

Full schema: sdk/python/agentweave/schema.py

Proxy — zero-code observability

For agents you can't instrument with decorators (Claude Code, Node.js, any runtime), run the AgentWeave proxy — a transparent HTTP server that sits between your agents and their LLM providers. Works with Claude Code out of the box — just set ANTHROPIC_BASE_URL in ~/.claude/settings.json (setup guide).

pip install "agentweave[proxy]"
agentweave proxy start --port 4000 --endpoint http://localhost:4318 --agent-id my-agent

# Point agents at the proxy — no code changes needed
export ANTHROPIC_BASE_URL=http://localhost:4000
export GOOGLE_GENAI_BASE_URL=http://localhost:4000
export OPENAI_BASE_URL=http://localhost:4000

OpenAI/Codex streaming note:

• /v1/chat/completions needs stream_options.include_usage=true for token usage
• /v1/responses and /codex/responses do not support stream_options; usage should arrive in the final response.completed event
• AgentWeave handles this difference in the proxy so the traced spans still get tokens/cost when upstream provides them

One port, all providers. Every LLM call gets a span automatically.

Docker / k8s setup: see deploy/docker/Dockerfile

Backends

AgentWeave emits standard OTLP HTTP — works with any compatible backend:

Docs

Development

git clone https://github.com/arniesaha/agentweave && cd agentweave
pip install -e "./sdk/python[dev]"

pytest sdk/python                                    # 237 Python tests
(cd sdk/js && npm ci && npx jest --verbose)           # 10 TypeScript tests
(cd sdk/go && go test ./... -v)                       # 4 Go tests

License

MIT