Skip to main content
When an agent produces an unexpected result, you need more than just the final answer — you need to see every decision that led to it. Scout gives you a complete picture of every agent session through two views in Studio: History, which shows every conversation your agent has had, and Logs, which breaks each session down into a step-by-step execution trace. Together they let you trace any interaction from the user’s first message to the final response, understand exactly which tools were called and why, and catch issues before they become patterns.

​
Where to Look

In Scout Studio, open any agent and use these two views:
  • History — review prior sessions and conversations, with timestamps, tags, and summaries
  • Logs — inspect every tool call, model decision, and execution event in a session
Start with History to find the session you want to investigate, then open Logs to see exactly what happened step by step.

​
Activity Logs: History

The History tab shows every session your agent has handled. Each row includes:
  • Session ID — a unique identifier for the interaction
  • Timestamp — when the session started and how long it ran
  • Tags — any metadata tags attached when the session was created
  • Summary — a brief description of the conversation
Click any session row to open the full conversation thread. You’ll see the complete message exchange between the user and the agent, which tools were called and what they returned, and the final response the agent delivered. This is the fastest way to review what a user actually experienced.

​
Execution Traces: Logs

The Logs tab gives you a step-by-step trace of every event in a session. Each entry captures one thing the agent did — a model call, a tool invocation, an error — in the order it happened.
Event typeWhat it shows
llm_callThe prompt sent to the model and the response returned
tool_callThe tool name, input arguments, and output received
tool_errorA tool call that failed, with the error message
session_startTimestamp and metadata when the session began
session_endTimestamp, duration, and final status when the session closed
Use the Logs view when History shows a bad output but you can’t tell why. The llm_call entries show you exactly what context the model received at each step — so you can spot truncated history, missing tool results, or a prompt that drifted off course. The tool_call entries show you the exact input the agent passed to each tool and the exact output it got back, so you can verify tools are being used correctly.

​
Debugging a failed tool call

1

Find the session

Open the History tab and click the session where the bad output occurred.
2

Switch to Logs

In the session detail view, open the Logs tab and scroll to find the relevant sequence of events.
3

Find the tool_error event

Look for a tool_error entry. It shows the input the agent passed to the tool and the error message the tool returned.
4

Check what the model did next

Look at the llm_call that follows the error. This shows how the model interpreted the failure and what decision it made — whether it retried, tried a different tool, or gave up.
This workflow catches most issues without needing to reproduce them locally.

​
Tool Usage

The Logs view surfaces every tool call your agent made in a session — reads, writes, API calls, code executions, and any other tool the agent invoked. For each call you can see:
  • Which tool was called and when
  • What input the agent passed — the exact arguments, queries, or payloads
  • What the tool returned — the full response, including any errors
  • How long the call took
Reviewing tool usage helps you understand whether your agent is using tools efficiently, whether it’s calling the right tools in the right order, and whether any external service is causing slowdowns or failures. It also gives you a clear audit trail for any actions the agent took — writes to a CRM, emails sent, records updated — so you can verify the agent behaved as intended.
When a tool input uses Variables, the Logs view shows the resolved values that were passed to the tool. Sensitive header values are sanitized rather than logged raw.

​
Interaction Tags

You can attach metadata tags to any agent session by including them in the API request. Scout stores these tags on the session record so you can filter History by them later. Common tagging patterns:
  • source:eval — test and evaluation traffic
  • source:end_user — live user sessions
  • campaign:q1 — sessions tied to a specific campaign
  • team:support — sessions from a particular team
Tags are observability metadata only. They are not added to the agent’s prompt, not passed to tools, and do not affect how the agent behaves. Sessions without tags work exactly the same way.

​
Tag rules

  • Up to 20 tags per request
  • Up to 32 characters per tag
  • Allowed characters: lowercase letters, numbers, :, _, and -
  • Scout automatically trims whitespace, lowercases values, removes empty tags, and deduplicates
  • Requests with invalid tags return 400 Bad Request

​
Sending tags in a request

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"]
)

import Scout from "scoutos";

const client = new Scout({ 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"],
});

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

​
Filtering History by tags

In the History tab, use the tag filter to find sessions by tag value:
  • Press Enter or , to turn a typed value into a filter chip
  • Use ANY to return sessions that contain at least one of your selected tags
  • Use ALL to return sessions that contain every selected tag
  • Tag filters work alongside date range, duration, and pagination controls
This makes it straightforward to compare evaluation runs against live user traffic, measure how different campaigns are using your agent, or isolate sessions from a specific team — without touching your agent configuration.

​
Using Observability to Build Trust

Observability isn’t just for debugging — it’s how you and your team build confidence that agents are doing what you intended. Verify behavior after instruction changes. After updating your agent’s instructions, run a few test sessions and review the Logs to confirm the agent is following the new guidance. Don’t assume — check. Audit high-stakes actions. For agents that write to a CRM, send emails, or modify records, use tool call logs to confirm every action was appropriate. The logs give you a timestamped record of exactly what the agent did and with what input. Identify patterns in failures. Filter History by failed sessions and look for common causes across Logs entries. A recurring tool_error on the same tool often points to a misconfigured integration, a rate limit, or an instruction that produces bad tool inputs. Compare test traffic to real traffic. Use source:eval and source:end_user tags to keep evaluation sessions separate from live sessions, then compare them side by side in History to catch regressions before they affect users.

​
Best Practices

  • Use a consistent prefix scheme for tags — source:, campaign:, team: — so filters stay predictable
  • Keep tag values short and exact; avoid spaces and special characters
  • Use source:eval consistently for all test and evaluation traffic so it’s easy to filter out of production metrics
  • Don’t put sensitive or user-identifying information in tags — they appear in the Studio UI and can be seen by workspace members
  • Review logs for the first few runs after any significant change to agent instructions, tools, or model settings