Agent Tracing

The foundation of AI agent observability. Agent Tracing wraps your entire agent workflow, creating the root trace that connects all operations together and gives you complete visibility from start to finish.

Agent Tracing is designed for your main API endpoints and entry points—the functions that process incoming requests and orchestrate your entire agent workflow.

⚠️

Golden Rule: Every request that enters your system must start with Agent Tracing. Without this wrapper, the root context won’t be created and inner nodes won’t be linked together.

How It Works

Agent Tracing creates a root context for your entire workflow, allowing you to:

Track the complete lifecycle of your application
Correlate all operations within a single request
Monitor performance and errors across the entire flow
Maintain a hierarchical view of your system’s behavior

Implementation

Python

agent.py


from handit_service import tracker
 
# Async version
@tracker.start_agent_tracing(key="invoice-assistant")
async def process_invoice(user_input: str) -> str:
    """
    Main function of your agent.
    Everything that happens inside will be linked to the same trace.
    """
    # Your agent logic here
    answer = await generate_answer(user_input)
    return answer
 
# Sync version
@tracker.start_agent_tracing(key="invoice-assistant")
def process_invoice_sync(user_input: str) -> str:
    """
    Synchronous version of the agent.
    Same tracing capabilities, just without async/await.
    """
    # Your agent logic here
    answer = generate_answer_sync(user_input)
    return answer

Key Features

Automatic Context Creation
- Creates a unique trace ID for each request
- Maintains context throughout the entire execution
- Links all child operations together
Error Handling
- Automatically captures and reports errors
- Includes stack traces and error context
- Maintains error information in the trace
Performance Monitoring
- Tracks total execution time
- Monitors individual operation durations
- Identifies bottlenecks in the workflow
Operation Correlation
- Links all operations within a request
- Maintains parent-child relationships
- Provides end-to-end visibility

Real-World Examples

Agent Tracing is essential for any entry point that processes requests or executes workflows. Here are common scenarios:

Python

chat_agent.py


# Chat Agent - Entry point for conversational AI
@app.post("/api/v1/chat")
@tracker.start_agent_tracing(key="chat-agent-v1")
async def handle_chat(request: ChatRequest):
    """
    Main entry point for chat interactions.
    Tracks the entire conversation flow, including:
    - User messages and context
    - AI model responses
    - Tool executions
    - Conversation state
    """
    try:
        # Process the chat request
        response = await chat_agent.process(
            message=request.message,
            context=request.context,
            user_id=request.user_id
        )
        return response
    except Exception as e:
        logger.error(f"Chat processing error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

scheduler_agent.py


# Agentic Scheduler - Entry point for AI-powered scheduling
@app.post("/api/v1/schedule")
@tracker.start_agent_tracing(key="scheduler-agent-v1")
async def handle_scheduling(request: ScheduleRequest):
    """
    Main entry point for AI scheduling operations.
    Tracks the entire scheduling workflow:
    - Calendar analysis
    - Conflict resolution
    - Meeting optimization
    - Notification handling
    """
    try:
        schedule = await scheduler_agent.process(
            participants=request.participants,
            preferences=request.preferences,
            constraints=request.constraints
        )
        return schedule
    except Exception as e:
        logger.error(f"Scheduling error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

call_agent.py


# Call Agent - Entry point for AI call handling
@app.post("/api/v1/call")
@tracker.start_agent_tracing(key="call-agent-v1")
async def handle_call(request: CallRequest):
    """
    Main entry point for AI call processing.
    Tracks the entire call workflow:
    - Call initialization
    - Real-time transcription
    - Intent recognition
    - Response generation
    - Call summary
    """
    try:
        call_result = await call_agent.process(
            audio_stream=request.audio,
            call_metadata=request.metadata,
            user_context=request.context
        )
        return call_result
    except Exception as e:
        logger.error(f"Call processing error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

document_agent.py


# Document Processing Agent - Entry point for document analysis
@app.post("/api/v1/process-document")
@tracker.start_agent_tracing(key="document-agent-v1")
async def handle_document(request: DocumentRequest):
    """
    Main entry point for document processing.
    Tracks the entire document workflow:
    - Document parsing
    - Content extraction
    - Analysis and classification
    - Summary generation
    """
    try:
        result = await document_agent.process(
            document=request.document,
            processing_type=request.type,
            options=request.options
        )
        return result
    except Exception as e:
        logger.error(f"Document processing error: {e}")
        raise HTTPException(status_code=500, detail=str(e))

JavaScript

chat_agent.js


// Chat Agent - Entry point for conversational AI
app.post('/api/v1/chat', startAgentTracing(async (req, res) => {
    try {
        // Process the chat request
        const response = await chatAgent.process({
            message: req.body.message,
            context: req.body.context,
            userId: req.body.userId
        });
        res.json(response);
    } catch (error) {
        logger.error(`Chat processing error: ${error}`);
        res.status(500).json({ error: error.message });
    }
}));

scheduler_agent.js


// Agentic Scheduler - Entry point for AI-powered scheduling
app.post('/api/v1/schedule', startAgentTracing(async (req, res) => {
    try {
        const schedule = await schedulerAgent.process({
            participants: req.body.participants,
            preferences: req.body.preferences,
            constraints: req.body.constraints
        });
        res.json(schedule);
    } catch (error) {
        logger.error(`Scheduling error: ${error}`);
        res.status(500).json({ error: error.message });
    }
}));

call_agent.js


// Call Agent - Entry point for AI call handling
app.post('/api/v1/call', startAgentTracing(async (req, res) => {
    try {
        const callResult = await callAgent.process({
            audioStream: req.body.audio,
            callMetadata: req.body.metadata,
            userContext: req.body.context
        });
        res.json(callResult);
    } catch (error) {
        logger.error(`Call processing error: ${error}`);
        res.status(500).json({ error: error.message });
    }
}));

document_agent.js


// Document Processing Agent - Entry point for document analysis
app.post('/api/v1/process-document', startAgentTracing(async (req, res) => {
    try {
        const result = await documentAgent.process({
            document: req.body.document,
            processingType: req.body.type,
            options: req.body.options
        });
        res.json(result);
    } catch (error) {
        logger.error(`Document processing error: ${error}`);
        res.status(500).json({ error: error.message });
    }
}));

Best Practices

Implementation Guidelines

Always Start with Agent Tracing
- Wrap your main entry points (API endpoints, webhooks, scheduled tasks)
- Use meaningful keys that describe your agent’s purpose
- Make keys consistent across environments
Error Handling
- Let errors propagate naturally through your code
- Don’t suppress exceptions within the traced function
- Use try-catch blocks when needed for specific error handling
Keep Traces Clean
- Avoid unnecessary nesting of agent traces
- Use appropriate granularity for your workflow
- Remove sensitive information from trace data

With Agent Tracing in place, you’ll have complete visibility into your application’s behavior, making it easier to debug issues and optimize performance.

Next Steps

Ready to add more detailed tracing to your agent components?

Learn about LLM Node Tracing for AI model interaction tracking
Explore Tool Tracing for function and tool execution monitoring