Agents

Track individual agent performance and inter-agent interactions.

Agent Identity

Define agent identity in your code:

from risicare import agent
 
@agent(name="researcher", role="specialist")
def research_agent(query: str):
    # Agent code here
    pass

Or with context managers:

from risicare import agent_context
 
with agent_context(
    "planner-001",                   # agent_id (required, positional)
    agent_name="planner",
    agent_role="orchestrator",
    agent_type="custom",
    version=1,
):
    # Agent code here
    pass

Agent Attributes

Agent Roles

Agent Dashboard

The KPI strip shows: Total Agents, Invocations (with trace count), Success Rate (with errors), Avg Latency (with P95), Total Errors (with error rate), and Total Cost (with tokens).

Agent List

View all agents with metrics:

Agent Detail

Deep dive into a single agent:

• Performance: Latency percentiles, throughput
• Tokens: Usage by model
• Errors: Top error codes, failure patterns
• Interactions: Agents it calls and is called by

Agent Hierarchy

Track parent-child relationships:

@agent(name="orchestrator", role="orchestrator")
def orchestrator():
    with agent_context(
        "researcher-001",
        agent_name="researcher",
        agent_role="specialist",
    ):
        research()
 
    with agent_context(
        "writer-001",
        agent_name="writer",
        agent_role="specialist",
    ):
        write()

Visualized as:

orchestrator (orchestrator)
├── researcher (specialist)
└── writer (specialist)

Inter-Agent Communication

Track messages between agents:

from risicare import trace_message
 
@trace_message(target="researcher-001", target_name="Researcher")
def send_research_request(task: str):
    return researcher.process(task)

Message Types

Message Attributes

Agent Delegation

Track when agents delegate tasks:

from risicare import trace_delegate
 
@trace_delegate(target="executor-001", target_name="Executor")
def delegate_execution(plan: dict):
    return executor.execute(plan)

Agent Analytics

Performance Comparison

Compare agents across:

• Latency (P50, P95, P99)
• Error rate
• Token efficiency
• Cost per operation

Interaction Graph

Visual network showing:

• Agent nodes
• Communication edges
• Message volume
• Error paths

Bottleneck Analysis

Identify slow agents:

• Agents on critical path
• High-latency operations
• Token-heavy agents
• Error-prone agents

Agent Iterations

Record iteration counts on iterative agent loops via agent metadata. (Note: this stores the value in the span's metadata; the dedicated iteration / max_iterations agent analytics are not yet auto-populated — see the in-flight note above.)

@agent(name="refiner", role="specialist")
def iterative_refine(content: str, max_iterations: int = 3):
    for i in range(max_iterations):
        with agent_context(
            "refiner-001",
            agent_name="refiner",
            metadata={"iteration": i + 1}
        ):
            content = refine_step(content)
            if is_good_enough(content):
                break
    return content

Filtering Agents

# By name
name:researcher

# By role
role:orchestrator

# By performance
latency_p99:>5000
error_rate:>0.1

# By activity
invocations:>1000

Next Steps