AgentScope

Build transparent, observable AI agents using AgentScope — a framework for creating agents you can see, understand, and trust with full execution tracing and debugging.

Overview

AgentScope provides three pillars of observability for AI agents: execution tracing (every step recorded with inputs, outputs, timing), decision logging (why the agent chose action A over B), and live debugging (inspect, pause, and replay agent executions). It integrates with monitoring stacks like OpenTelemetry, Prometheus, Datadog, and Grafana.

Instructions

Installation

pip install agentscope

Or with Node.js:

npm install agentscope

Basic Agent with Tracing

from agentscope import Agent, Tracer

tracer = Tracer(output="./traces/")

agent = Agent(
    name="research-assistant",
    model="claude-sonnet-4-20250514",
    tracer=tracer,
)

result = agent.run("Summarize the key findings from this paper")

trace = tracer.latest()
print(f"Steps: {trace.step_count}")
print(f"Duration: {trace.duration_ms}ms")
print(f"Tokens used: {trace.total_tokens}")

for step in trace.steps:
    print(f"  [{step.type}] {step.name}: {step.duration_ms}ms")
    print(f"    Input: {step.input[:100]}...")
    print(f"    Output: {step.output[:100]}...")

Decision Logging

Track why an agent made specific choices:

from agentscope import Agent, DecisionLogger

logger = DecisionLogger(
    log_alternatives=True,
    log_reasoning=True,
)

agent = Agent(
    name="trading-agent",
    model="claude-sonnet-4-20250514",
    decision_logger=logger,
    tools=["market-data", "portfolio", "trade-executor"],
)

result = agent.run("Review portfolio and suggest rebalancing")

for decision in logger.decisions:
    print(f"Decision: {decision.action}")
    print(f"Reasoning: {decision.reasoning}")
    for alt in decision.alternatives:
        print(f"  - {alt.action} (score: {alt.score:.2f}, rejected: {alt.rejection_reason})")

Multi-Agent Observability

from agentscope import AgentTeam, Tracer, Dashboard

tracer = Tracer(output="./traces/")

team = AgentTeam(
    agents=[
        Agent(name="researcher", model="claude-sonnet-4-20250514", role="research"),
        Agent(name="analyst", model="claude-sonnet-4-20250514", role="analysis"),
        Agent(name="writer", model="claude-sonnet-4-20250514", role="writing"),
    ],
    tracer=tracer,
    coordination="sequential",
)

result = team.run("Create a market analysis report for Q4 2025")

for message in tracer.messages():
    print(f"[{message.sender} → {message.receiver}] {message.content[:80]}...")

dashboard = Dashboard(tracer)
dashboard.serve(port=8080)

Structured Audit Trails

from agentscope import Agent, AuditTrail

audit = AuditTrail(
    storage="./audit_logs/",
    format="jsonl",
    include_timestamps=True,
    redact_pii=True,
)

agent = Agent(
    name="claims-processor",
    model="claude-sonnet-4-20250514",
    audit_trail=audit,
)

result = agent.run("Process insurance claim #12345")

report = audit.export(
    trace_id=result.trace_id,
    format="pdf",
    include_decisions=True,
)
report.save("audit-claim-12345.pdf")

OpenTelemetry Integration

from agentscope import Agent, Tracer
from agentscope.exporters import OTelExporter

exporter = OTelExporter(
    endpoint="http://localhost:4317",
    service_name="my-agent-service",
)

tracer = Tracer(exporters=[exporter])
agent = Agent(name="support-agent", model="claude-sonnet-4-20250514", tracer=tracer)
# Traces automatically appear in Jaeger/Grafana/Datadog

Examples

Example 1: Debug a Multi-Agent Research Pipeline

from agentscope import AgentTeam, Tracer, Replayer

tracer = Tracer(output="./traces/")
team = AgentTeam(
    agents=[
        Agent(name="researcher", model="claude-sonnet-4-20250514", role="research"),
        Agent(name="analyst", model="claude-sonnet-4-20250514", role="analysis"),
    ],
    tracer=tracer,
)

result = team.run("Analyze Q4 revenue trends for FAANG companies")

# Replay and inspect each step
trace = tracer.latest()
replayer = Replayer(trace)
for step in replayer:
    print(f"Step {step.index}: {step.name} — {step.duration_ms}ms")
    if step.is_decision:
        print(f"  Chose: {step.decision.action}, Alternatives: {len(step.decision.alternatives)}")

Example 2: Production Audit Trail for Insurance Claims

from agentscope import Agent, AuditTrail
from agentscope.exporters import PrometheusExporter

audit = AuditTrail(storage="./audit_logs/", format="jsonl", redact_pii=True)
metrics = PrometheusExporter(port=9090)

agent = Agent(
    name="claims-processor",
    model="claude-sonnet-4-20250514",
    audit_trail=audit,
    tracer=Tracer(exporters=[metrics]),
)

result = agent.run("Process insurance claim #67890 for water damage — $12,400")
report = audit.export(trace_id=result.trace_id, format="pdf", include_decisions=True)
report.save("audit-claim-67890.pdf")
# Prometheus exposes: agent_step_duration_seconds, agent_total_tokens, agent_error_count

Guidelines

• Enable log_alternatives=True during development to understand agent decision-making
• Use the Dashboard web UI for visual debugging — much easier than reading JSON traces
• Set redact_pii=True in production to avoid logging sensitive data
• OpenTelemetry export integrates with existing monitoring stacks (Datadog, Grafana, New Relic)
• For multi-agent systems, trace inter-agent messages to find communication bottlenecks
• Execution replay is invaluable for reproducing bugs — save traces from production errors
• Keep audit trail storage separate from application logs for compliance isolation