This guide walks you through how to manually integrate Handit.AI into your Node.js or Python application, giving you full control over your agent's setup, instrumentation, and monitoring.
Installation
Install the Handit.AI SDK in your project:
npm install @handit.ai/node
pip install handit
Basic Configuration
Configure the Handit.AI client using your API key (stored in environment variables).
from handit import HanditTracker
tracker = HanditTracker(api_key=os.getenv("HANDIT_API_KEY"))
Agent Configuration
Before instrumenting your agent, download the agent configuration file from the Agents tab in the Handit.AI dashboard. This file maps node names to their corresponding slugs and is used for tracing:
{
"agent-name": {
"node-name": "node-slug"
}
}
This mapping file is essential for the traceAgentNode function as it provides the correct slugs for each node in your agent.
agent_config = {
"agent": {
"name": "Text Processing Agent",
"slug": "text-processing-agent",
"description": "Processes and optimizes text through multiple stages"
},
"nodes": [
{
"name": "Text Preprocessor",
"slug": "text-preprocessor",
"description": "Preprocesses input text for analysis",
"type": "tool",
"problem_type": "text-preprocessing",
"next_nodes": ["sentiment-analyzer"]
},
{
"name": "Sentiment Analyzer",
"slug": "sentiment-analyzer",
"description": "Analyzes text sentiment",
"type": "model",
"problem_type": "sentiment-analysis",
"next_nodes": ["response-formatter"]
}
]
}
Implementation
Agent Wrapper: Trace the Entire Workflow
The agent wrapper (startAgentTracing) should wrap the main function that executes your entire agent flow. This could be:
The main endpoint handler if your agent is exposed via an API
The primary function that orchestrates all agent operations
The top-level function that processes the complete agent workflow
The wrapper ensures that all operations within your agent are properly traced and connected.
import { startAgentTracing } from '@handit.ai/node';
// Example: API endpoint handler
async function handleAgentRequest(req, res) {
const result = await processAgentFlow(req.body);
res.json(result);
}
// Wrap the endpoint handler
const tracedEndpoint = startAgentTracing(handleAgentRequest);
// Use in your API
app.post('/agent', tracedEndpoint);
// Example: Main agent orchestrator
async function processAgentFlow(input) {
// Your complete agent logic here
const preprocessed = await preprocessData(input);
const analyzed = await analyzeData(preprocessed);
const formatted = await formatResponse(analyzed);
return formatted;
}
// Wrap the main orchestrator
const tracedAgent = startAgentTracing(processAgentFlow);
from handit import start_agent_tracing
# Example: API endpoint handler
async def handle_agent_request(request):
result = await process_agent_flow(request.json)
return result
# Wrap the endpoint handler
traced_endpoint = start_agent_tracing(handle_agent_request)
# Use in your API
@app.post("/agent")
async def agent_endpoint(request):
return await traced_endpoint(request)
# Example: Main agent orchestrator
async def process_agent_flow(input_data):
# Your complete agent logic here
preprocessed = await preprocess_data(input_data)
analyzed = await analyze_data(preprocessed)
formatted = await format_response(analyzed)
return formatted
# Wrap the main orchestrator
traced_agent = start_agent_tracing(process_agent_flow)
Node Wrapper: Trace Individual Functions
The node wrapper (traceAgentNode) should wrap each individual function that performs a specific operation in your agent. This includes:
Model calls (e.g., GPT, Claude)
Tool executions
Data processing functions
Any other discrete operation
It's crucial to:
Pass the actual input data through the wrapper (not just metadata)
Return the complete output from the function
Use the correct slug from your agent config file
import { traceAgentNode } from '@handit.ai/node';
import { OpenAI } from 'openai';
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY
});
// Example: Model node
async function gptNode(messages) {
const response = await openai.chat.completions.create({
messages,
model: "your-model-name"
});
// Return the complete model response
return response.choices[0].message.content;
}
// Example: Tool node
async function dataProcessor(input) {
// Process the data
const processed = await processData(input);
// Return the complete processed result
return processed;
}
// Wrap nodes with tracing
const tracedGpt = traceAgentNode({
agentNodeId: "text-preprocessor", // Use the slug from your agent config
callback: gptNode
});
const tracedProcessor = traceAgentNode({
agentNodeId: "data-processor", // Use the slug from your agent config
callback: dataProcessor
});
// Use in your agent
async function processAgentFlow(input) {
// Pass the actual input data through the wrapper
const processed = await tracedProcessor(input);
const response = await tracedGpt(processed);
return response;
}
from handit import trace_agent_node
from openai import OpenAI
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
# Example: Model node
async def gpt_node(messages):
response = await client.chat.completions.create(
messages=messages,
model="your-model-name"
)
# Return the complete model response
return response.choices[0].message.content
# Example: Tool node
async def data_processor(input_data):
# Process the data
processed = await process_data(input_data)
# Return the complete processed result
return processed
# Wrap nodes with tracing
traced_gpt = trace_agent_node(
agent_node_id="text-preprocessor", # Use the slug from your agent config
callback=gpt_node
)
traced_processor = trace_agent_node(
agent_node_id="data-processor", # Use the slug from your agent config
callback=data_processor
)
# Use in your agent
async def process_agent_flow(input_data):
# Pass the actual input data through the wrapper
processed = await traced_processor(input_data)
response = await traced_gpt(processed)
return response
Best Practices
Environment Variables
Store API keys securely (e.g., .env files)
Never commit secrets to version control
Error Handling
Wrap model/tool calls with proper try/catch logic
Log exceptions with helpful context
Traced functions automatically propagate errors to Handit for visibility
Security
Sanitize sensitive inputs before sending to Handit
Validate incoming data
Implement access controls on endpoints using agents