Skip to main content
The Agent Platform uses event monitoring to enable you to see how your agent is performing in both real-time and post-run. Understanding what your agent does when it’s running can help you both improve the agent you’ve built and build other agents based on the data you extract.

​
How it works

There are two ways to monitor agent performance through the Agent Platform:
  • Agent Platform SDK (Real-time monitoring): Subscribe to live updates as your agent runs. With our SDK, you can track event changes as they happen, status updates, and more. You do not need a trajectory ID — the SDK handles this internally.
  • Agent Platform API (Post-run and real-time analysis): Use the trajectory endpoints to view your agent’s performance after it finishes running. You can retrieve a complete log of events, including thoughts, actions, answers, and screenshots associated with a specific trajectory ID. Use the GET /api/v1/trajectories/{id}/changes endpoint to retrieve new events.

​
View an event via SDK

The Agent Platform allows you to listen to events, check for status updates, and more. The following snippets show you how to monitor events using our Agent Platform SDK:

​
Step 1: Start the task

Use run() (or runStepByStep()) to run your task. For example: 
const task = await agent.run('Book a restaurant reservation');

​
Step 2: Listen to events

Execute one of the following commands to view and/or monitor agent performance through events:

​
Step 2a: Monitor real-time updates (Optional)

task.onUpdate((event) => {
  console.log('Event:', event.type, event.data);
});

​
Step 2b: Track status changes (Optional)

task.onStatusChange((status) => {
  console.log('Status changed to:', status);
});

​
Step 2c: Handle errors (Optional)

task.onError((error) => {
  console.log('Error occurred:', error);
});
Note: You do not get a trajectory ID from the SDK task. The SDK internally manages trajectories and provides these event methods for monitoring.

​
View an event via API

A trajectory is the recorded sequence of actions taken by the agent during a task, including detailed event data. You can monitor and analyze an agent’s activity by retrieving a trajectory through the Agent Platform’s APIs. Each trajectory contains a list of time-stamped events that describe every action the agent performed during a task.

​
Step 1: Identify the trajectory ID

When creating a trajectory via the API (not the SDK), the API response will include a trajectory_id. This is the ID you can use to fetch event data. 
const response = await fetch('/v1/agents/{agent_identifier}/trajectories', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ task: { type: 'web', objective: 'What is H Company?' } })
});

const trajectory = await response.json();
console.log('Trajectory ID:', trajectory.id);

​
Step 2: Retrieve the trajectory

Use the trajectory ID to make an API request and fetch the full execution data for the task: 
const response = await fetch(`/v1/trajectories/${trajectory.id}`);
const fullTrajectory = await response.json();

​
Step 3: View the events

The events array in the trajectory API response contains the full event log for the task — showing what the agent thought, did, and ultimately answered. 
console.log('All task events:', fullTrajectory.events);
Each item in the array is an event object with a structure like this: 
{
  "type": "ChatMessageEvent",
  "timestamp": "2025-07-29T12:11:14.057370Z",
  "data": {
    "type": "answer",
    "content": "H Company, also known as H, is a French artificial intelligence startup..."
  }
}

​
Event properties

The following table defines key event properties.
PropertyTypeDescription
typestringHigh-level event category, e.g., "ChatMessageEvent", "AgentStartedEvent".
timestampstring (ISO 8601)When the event occurred (UTC).
dataobjectEvent-specific details, e.g., message content, screenshot URL, action info.
data.typestringMore specific sub-type of the event, e.g., "answer", "thought", "screenshot", "action", "highlevel", "thinker", "navigator", "web_action", "notes".
data.contentstringActual message, screenshot URL, user action description, etc.
data.sender_idstringWho produced the message ("agent", "user", etc.).
data.extra_contentobjectOptional additional structured data.

​
Event types

The following table defines key event types. The list of available event types may expand over time.
PropertyTypeDescription
ChatMessageEventstringTriggered when a message is sent or received in a conversation. Contains data.type, data.content, data.sender_id, and data.extra_content.
AgentStartedEventstringIndicates an agent has begun execution. data may contain additional info.
AgentCompletionEventstringSignals that an agent has finished its task or produced a final response. Includes data.reason ("completed", "timed_out", "error", or string).
WebActionEventstringDescribes web actions with pre- and post-action screenshots. Contains a nested data.action object with action_type (e.g., "goto", "click", "write", "press", "scroll", "select", "hover", "wait"), and optional tab, url, element, text, key, direction, or value.