Observability

When your agent does something unexpected, you need to know why. Scout gives you two tools for that: a session history view and detailed execution logs. Together they let you trace any interaction from the user’s first message to the final response.

Where to Look

In Scout Studio, open an agent and use these views:

• History to review prior sessions and conversations
• Logs to inspect tool usage, execution traces and errors

Start with History to find the session, then drill into Logs to see exactly what happened step by step.

History

The History tab shows every session your agent has handled. Each row includes the session ID, timestamp, any tags you attached and a summary of the conversation.

Click a session to open it. You’ll see:

• The full message thread between the user and the agent
• Which tools were called and what they returned
• The final response the agent sent

This is the fastest way to review what a user actually experienced.

Logs

The Logs tab gives you a step-by-step execution trace for each session. Each entry captures one event in the agent’s run.

Common log event types:

Use Logs when History shows a bad output but you can’t tell why. The llm_call events show you exactly what context the model received, so you can spot truncated history, missing tool results or a prompt that went off the rails.

Debugging a failed tool call

1. Find the session in History
2. Switch to Logs and filter or scroll to that session
3. Look for a tool_error event — it shows the input that caused the failure
4. Check the llm_call after the error to see how the model handled it

This workflow catches most issues without needing to reproduce them locally.

Interaction Tags

You can attach optional tags when sending an agent interaction. Scout stores these tags on the session’s observability record so you can filter History later.

Common examples:

• source:eval
• source:end_user
• campaign:q1
• team:support

Tags are observability metadata only:

• They are not added to the agent prompt
• They are not passed to tools
• Requests without tags behave normally

Tag Rules

• Up to 20 tags per request
• Up to 32 characters per tag
• Allowed characters: lowercase letters, numbers, :, _ and -
• Scout trims whitespace, lowercases values, drops empty tags and deduplicates them
• Invalid tags return 400 Bad Request

Example Request

Use tags on agent interaction requests when you want the resulting session to be filterable in History.

{
  "messages": [
    {
      "role": "user",
      "content": "Run this evaluation prompt against the latest support workflow"
    }
  ],
  "tags": ["source:eval", "campaign:q1"]
}

TypeScript SDK

import { ScoutClient } from "scoutos";
 
const client = new ScoutClient({ apiKey: "YOUR_API_KEY" });
 
await client.agents.interact({
  agentId: "agent_abc123",
  messages: [
    {
      role: "user",
      content: "Run this evaluation prompt against the latest support workflow"
    }
  ],
  tags: ["source:eval", "campaign:q1"]
});

Python SDK

from scoutos import Scout
 
client = Scout(api_key="YOUR_API_KEY")
 
client.agents.interact(
    agent_id="agent_abc123",
    messages=[
        {
            "role": "user",
            "content": "Run this evaluation prompt against the latest support workflow"
        }
    ],
    tags=["source:eval", "campaign:q1"]
)

Pass tags in the same request object you already use for interact or interact_async.

Filter History by Tags

In an agent’s History tab, you can filter sessions with free-text tags.

• Press Enter or , to turn a value into a chip
• Use ANY to match sessions with at least one selected tag
• Use ALL to match sessions that contain every selected tag
• Tag filters work alongside date, tool and pagination controls

This makes it easy to compare evaluation runs against real user traffic without touching your agent configuration.

Best Practices

• Use a stable prefix like source:, campaign: or team:
• Keep tags short and exact so filtering stays predictable
• Use source:eval consistently for test traffic
• Avoid putting sensitive or user-identifying data in tags

Next Steps

• Getting Started with Agents: Build and test your first agent
• Async Interactions: Run long-lived agent tasks with callbacks
• Code Execution: Add deterministic compute to agent runs

Built with ❤️ by Scout OS