Overview
Call track_tool_use each time your agent invokes a tool or function within a message turn. A single turn can produce many tool calls — each one is stored as a separate row and is not deduplicated. Use the shared messageId / message_id to group all tool calls belonging to the same turn.
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) |
toolName | tool_name | string | The name of the tool being invoked — e.g. 'fetch_billing_info' |
Optional fields
| Field (Node / Browser) | Field (Python) | Type | Description |
|---|
status | status | string | Any string — 'success', 'failure', '200', '429', HTTP status codes, custom labels |
latencyMs | latency_ms | number | How long the tool call took in milliseconds |
input | input | any | Tool input payload (stored in properties.input) |
output | output | any | Tool output / result payload (stored in properties.output) |
timestamp | timestamp | ISO 8601 string | Override event time |
Examples
Trodo.track_tool_use({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
toolName: 'fetch_billing_info',
status: 'success',
latencyMs: 212,
input: { customerId: 'cus_8xp3nk7' },
output: { invoiceId: 'inv_4421', amount: 149.00, status: 'paid' },
});
// Successful tool call
await trodo.track_tool_use({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
distinctId: 'user_7hq29zal',
toolName: 'fetch_billing_info',
status: 'success',
latencyMs: 212,
input: { customerId: 'cus_8xp3nk7' },
output: { invoiceId: 'inv_4421', amount: 149.00, status: 'paid' },
});
// Downstream API rate limit
await trodo.track_tool_use({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
distinctId: 'user_7hq29zal',
toolName: 'fetch_billing_info',
status: '429',
latencyMs: 58,
input: { customerId: 'cus_8xp3nk7' },
});
# Successful tool call
await trodo.track_tool_use(
ToolUseProps(
agent_id='agt_abc12345',
conversation_id='conv_9kx2m7pq',
message_id='msg_01jf3t8r',
distinct_id='user_7hq29zal',
tool_name='fetch_billing_info',
status='success',
latency_ms=212,
input={'customer_id': 'cus_8xp3nk7'},
output={'invoice_id': 'inv_4421', 'amount': 149.00, 'status': 'paid'},
)
)
# Downstream API rate limit
await trodo.track_tool_use(
ToolUseProps(
agent_id='agt_abc12345',
conversation_id='conv_9kx2m7pq',
message_id='msg_01jf3t8r',
distinct_id='user_7hq29zal',
tool_name='fetch_billing_info',
status='429',
latency_ms=58,
input={'customer_id': 'cus_8xp3nk7'},
)
)
