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
bash
pip install agentscope
Or with Node.js:
bash
npm install agentscope
Basic Agent with Tracing
python
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:
python
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
python
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
python
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
python
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
python
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
python
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=Trueduring development to understand agent decision-making - Use the Dashboard web UI for visual debugging — much easier than reading JSON traces
- Set
redact_pii=Truein 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