Tools — observability and debugging

🔵 Read-only queries to agent traces and local tool testing. For a summary table of all engines, see "Tools Reference".

5.9 trace_tool

Queries to agent traces. Read-only queries to logs/events.db and logs/process-*.jsonl. operation selects the query:

operation	Purpose	Key parameters
`sessions`	list of sessions + aggregated statistics	`limit`, `offset`, `agent`, `only_errors`
`events`	timeline of session/process events	`session_id` or `pid`, `event_type`, `search`, `limit`
`transcript`	session dialogue	`session_id`, `search`
`search`	full-text search across transcripts	`query`, `limit`
`process`	raw JSONL trace of a process	`pid`, `event_type`, `include_tokens`, `search`, `limit`
`feedback`	likes/dislikes by template/user/session/value	`group_by`, `value`, `template`, `user_id`, `session_id`, `days`
`escalations`	escalation funnel: how many went to an operator (requested/resolved), by reasons and channels	`days`, `limit`
`blind_spots`	"blind spots": tools that often return a warning (empty search) or fail, by tool	`days`, `limit`

Visibility and scoping

trace_tool returns only what the caller is allowed to see:

Context	Scope	What can be queried
`admin_templates: "*"`	full	all sessions / processes
`admin_templates: "a,b"`	restricted	only these templates
no admin, but `user_id` present	user	only one's own sessions / transcripts / processes
neither	denied	`access denied`

An end-user agent (e.g. Felix) without an admin token automatically receives the user scope from X-User-Id of its session — its search sees only the current user's history, with no leaks between users.

5.21 Testing locally

agent-os tool <tool.yaml> '<json_args>'
agent-os office <tool.yaml> '<json_args>'        # с автозагрузкой officecli

Outputs: arguments, call_template (what the user sees before), output for the LLM, result_template (what is seen after). agent-os tool supports all kind: — site_tool, browser_tool, archive_tool, pdf_tool, rss_tool, json_tool, trace_tool, script_tool, state_tool, geo_tool, table_tool, chart_tool, visualize_tool, subagent_tool, email_tool, workflow_tool, duckdb_tool, sql_tool, shell_tool, file_tool, office_tool, vk_tool, ym_tool. A separate command agent-os office is a thin wrapper for the office kind: office_tool: on first run it downloads officecli and prints a block of file results.