Overview
Call track_agent_call when your agent receives a user message and is about to invoke the LLM. This event marks the start of an agent turn and captures the prompt, model configuration, and which system prompt version is running.
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 |
|---|
prompt | prompt | string | The user’s message or prompt text |
model | model | string | LLM identifier — e.g. 'gpt-4o', 'claude-3-5-sonnet' |
provider | provider | string | Provider name — 'openai', 'anthropic', 'google', etc. |
temperature | temperature | number | Sampling temperature passed to the LLM |
systemPromptVersion | system_prompt_version | string | Track system prompt iterations — e.g. 'v1', 'prod-2024-06' |
timestamp | timestamp | ISO 8601 string | Override event time (default: now) |
Examples
Trodo.track_agent_call({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
// distinctId is optional here — Trodo.identify() was called on login
prompt: 'What is the status of my last invoice?',
model: 'gpt-4o',
provider: 'openai',
temperature: 0.7,
systemPromptVersion: 'prod-2024-06',
});
await trodo.track_agent_call({
agentId: 'agt_abc12345',
conversationId: 'conv_9kx2m7pq',
messageId: 'msg_01jf3t8r',
distinctId: 'user_7hq29zal',
prompt: 'What is the status of my last invoice?',
model: 'gpt-4o',
provider: 'openai',
temperature: 0.7,
systemPromptVersion: 'prod-2024-06',
});
await trodo.track_agent_call(
AgentCallProps(
agent_id='agt_abc12345',
conversation_id='conv_9kx2m7pq',
message_id='msg_01jf3t8r',
distinct_id='user_7hq29zal',
prompt='What is the status of my last invoice?',
model='gpt-4o',
provider='openai',
temperature=0.7,
system_prompt_version='prod-2024-06',
)
)
Pass a systemPromptVersion to track which prompt version drives the best outcomes in your Insights charts.
