Log Trace
log_traceStore one immutable agent execution trace with input, output, tool calls, spans, cost and tokens to get a trace_id that later calls key on. Set evaluate to true to score it in the same call.
Instructions
Store one agent execution (input, output, tool calls, spans, cost, tokens) and get the trace_id later calls key on.
What it does. Writes one immutable trace to local storage; nothing is deduplicated. Only agent_name is required; store tool_calls, tools, cost and input/output so the rules can judge them. evaluate: true (with output) also scores it in this call, exactly as evaluate_output would. Full detail: iris://capabilities.
When not to use it. To score a stored trace (evaluate_output with its trace_id). To change one (delete_trace, then log again).
Returns. JSON: trace_id, status, cost_usd, cost_source, cost_estimate, evaluation.
Errors. IRIS_STORAGE_ERROR; IRIS_INVALID_ARGUMENT when evaluate is true without output. Unknown or malformed arguments are refused, naming the valid keys. Failures return {"error":{code,message,recovery}} with isError; follow recovery.
Siblings. evaluate_output — score the stored output; get_traces — query what was logged; delete_trace — remove one trace.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run | No | The batch this execution belongs to (a CI job id, a sweep); compare_runs compares two runs | |
| input | No | Agent input text — the user prompt or upstream input that produced this output | |
| spans | No | Detailed execution spans (hierarchical span tree with timings, attributes, events); a span without start_time takes the trace timestamp | |
| tools | No | Your MCP tools/list result, verbatim; lets the rules check call arguments later | |
| output | No | Agent output text — what the agent produced (pass to evaluate_output for scoring) | |
| case_key | No | What makes this the same question across runs (a fixture or test id); pairs traces. Derived from input when omitted | |
| cost_usd | No | Total cost in USD, stored as reported. Omitted: estimated from the token counts and the model (metadata.model or the spans) at list price, and marked estimated | |
| evaluate | No | Also score the stored trace in this call, exactly as evaluate_output would; requires output | |
| metadata | No | Opaque key-value tags (e.g. {requestId, userId, env}) — queryable in dashboard, not via get_traces filters | |
| eval_type | No | With evaluate: true, the bundle to run (default: every bundle, noted in the response) | |
| framework | No | Agent framework identifier (e.g., langchain, autogen, custom) | |
| timestamp | No | Trace timestamp (ISO 8601); defaults to now() when omitted | |
| agent_name | Yes | Agent name — used for filtering in get_traces (e.g., "customer-support-bot") | |
| latency_ms | No | Total execution time in milliseconds (end-to-end agent latency) | |
| session_id | No | The conversation this turn belongs to; groups its turns. Read from SEP-414 baggage when omitted | |
| tool_calls | No | Tool calls made, in order, each { tool_name, input?, output?, latency_ms?, error? }; the trajectory rules judge them | |
| token_usage | No | Token usage (prompt/completion/total, and cache_read_tokens / cache_creation_tokens: the cached part of prompt_tokens) — prices the trace when cost_usd is omitted |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| cost_usd | Yes | ||
| trace_id | Yes | ||
| evaluation | No | ||
| cost_source | No | ||
| cost_estimate | No |