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.
  • Agent Platform API (Post-run and real-time analysis): Use the trajectory endpoints to view your agent’s performance during and 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 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 executeWebTask() to run your task. For example: 
const task = await agent.executeWebTask('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)

Check when a task’s status changes (e.g., from pending to running, or completed): 
task.onStatusChange((status) => {
  console.log('Status changed to:', status);
});

​
Step 2c: Handle errors (Optional)

Listen for task errors as they occur: 
task.onStatusChange((status) => {
  console.log('Status changed to:', status);
});

​
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

After you start a task using the Agent Platform, you’ll receive a unique trajectory_id . The trajectory ID is the task or agent’s “run” and you’ll need it to fetch event data. 
const task = await agent.executeWebTask('What is H Company?');
console.log('Trajectory ID:', task.trajectoryId);

​
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/${trajectoryId}`);
const trajectory = 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. You can access it like this: 
console.log('All task events:', trajectory.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
typestringThe high-level event category. For example: "ChatMessageEvent", "AgentStartedEvent", "AgentCompletionEvent", "WebActionEvent"
timestampstring (ISO 8601)When the event occurred, in UTC timestamp format.
dataobjectDetails specific to the event type. For ChatMessageEvent, this includes a nested type, content, and other fields.
data.typestringA more specific sub-type of the event, for example "answer", "thought", "notes", "screenshot", "action", "last_url".
data.contentstringThe actual message, screenshot URL, user action description, or other content depending on data.type.
data.sender_idstringIdentifies who produced the message ("agent", "user", etc.). Present in most ChatMessageEvent types.
data.extra_contentobject(Optional) Additional structured data. Currently often empty ({}), but can be used for extensibility.

​
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.
AgentStartedEventstringIndicates that an agent has been initialized and begun execution.
AgentCompletionEventstringSignals that an agent has finished its task or produced a final response.
WebActionEventstringDescribe web actions with pre and post action screenshots in a structured manner.