> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitor Agent Activity: Logs, Traces, and Tool Usage
> Track every Scout agent action with execution logs, tool usage traces, and session history. See what agents did, when, and why — full auditability.
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 type | What it shows |
| --------------- | ------------------------------------------------------------- |
| `llm_call` | The prompt sent to the model and the response returned |
| `tool_call` | The tool name, input arguments, and output received |
| `tool_error` | A tool call that failed, with the error message |
| `session_start` | Timestamp and metadata when the session began |
| `session_end` | Timestamp, 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
Open the **History** tab and click the session where the bad output occurred.
In the session detail view, open the **Logs** tab and scroll to find the relevant sequence of events.
Look for a `tool_error` entry. It shows the input the agent passed to the tool and the error message the tool returned.
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](/agents/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
```python Python theme={null}
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"]
)
```
```typescript TypeScript theme={null}
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"],
});
```
```json JSON (raw request body) theme={null}
{
"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