Overview
Call track_agent_error whenever something goes wrong during an agent turn — rate limits, timeouts, guardrail blocks, tool failures, context length overflows, or any other exception. Use the same messageId / message_id as the originating track_agent_call event so errors are correlated to the turn in your dashboards.
Required fields
Node.js / Python SDK: distinctId / distinct_id is also required. Browser SDK: optional if the user has already called Trodo.identify() in the session.
| Field (Node / Browser) | Field (Python) | Type | Description |
|---|
agentId | agent_id | string | The registered agent ID — e.g. 'agt_abc12345' |
conversationId | conversation_id | string | Stable ID for the conversation thread |
messageId | message_id | string | Unique ID for this specific message turn |
distinctId | distinct_id | string | Links the event to a Trodo user (required in Node/Python; optional in Browser if identify() was called) |
Optional fields
| Field (Node / Browser) | Field (Python) | Type | Description |
|---|
errorType | error_type | string | Category — e.g. 'timeout', 'rate_limit', 'guardrail_block', 'tool_failure', 'context_length' |
errorMessage | error_message | string | Human-readable error description |
failedTools | failed_tools | string or string[] | The tool(s) that caused the error — a single name or a list |
traceback | traceback | string | Stack trace (stored in properties.traceback) |
timestamp | timestamp | ISO 8601 string | Override event time |
Examples
// Rate limit from the LLM provider
Trodo.track_agent_error({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
errorType: 'rate_limit',
errorMessage: 'OpenAI rate limit exceeded — too many requests per minute.',
});
try {
// ... agent logic
} catch (err) {
await trodo.track_agent_error({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
distinctId: 'user_7hq29zal',
errorType: 'tool_failure',
errorMessage: err.message,
failedTools: ['fetch_billing', 'send_email'],
traceback: err.stack,
});
}
import traceback as tb
try:
# ... agent logic
pass
except Exception as err:
await trodo.track_agent_error(
AgentErrorProps(
agent_id='agt_abc12345',
conversation_id='conv_9kx2m7pq',
message_id='msg_01jf3t8r',
distinct_id='user_7hq29zal',
error_type='tool_failure',
error_message=str(err),
failed_tools='fetch_billing_info',
traceback=tb.format_exc(),
)
)
Common errorType values: 'timeout', 'rate_limit', 'guardrail_block', 'tool_failure', 'context_length', 'invalid_response'. Use consistent values across your codebase so you can filter and group errors reliably in your dashboards.
