Observability

Observability helps you inspect how an agent handled a session, review prior conversations and organize interaction history with tags and filters.

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

Use them together when you need both a high-level session list and step-by-step execution details.

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 is useful when you want to compare evaluation runs against end-user traffic without changing 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