traces

telnyx-acp traces alice
telnyx-acp traces alice run-1a2b3c
telnyx-acp traces alice --limit 5 --local
telnyx-acp invoke support-agent --conversation alice --trace "What's the weather in Paris?"

Flag	Meaning
`--limit <n>`	How many of the newest runs to list, 20 by default, at most 50.
`--local`	Target the running `dev` instead of the deployed agent.

traces shows what a conversation’s runs did, step by step: each model call with its tokens and finish reason, each tool call with its outcome and the size of what it returned, the wait on an approval, and the reply’s delivery, each with its start and duration. It runs in the project directory and reads the agent named in agent.json. With a conversation alone, it lists that conversation’s newest runs, one line each:

run run-7f3e…  invoke  completed  3.6 s  4,803 tok  1 tool call  2 m 05 s ago
run run-51aa…  sms  completed  1.2 s  1,904 tok  14 m 10 s ago
run run-0c9d…  invoke  failed  412 ms  HARNESS_PROVIDER_ERROR  31 m 40 s ago

the steps of one: telnyx-acp traces alice <run>

With a run id too, it shows that run as a waterfall, each step’s time from the run’s start on the left:

run run-7f3e…  invoke  completed  3.6 s  4,803 tok  1 tool call
├─     +6 ms  model  meta-llama/Llama-3.3-70B-Instruct  step 1  1.3 s  2,333 tok  tool-calls
├─    +1.3 s  tool  web_search                          ok  772 ms  408 B
├─    +2.1 s  model  meta-llama/Llama-3.3-70B-Instruct  step 2  1.5 s  2,470 tok  stop
└─    +3.6 s  deliver  invoke                           ok  0 ms

invoke --trace prints the same waterfall under the reply, and /trace inside chat prints it for the last turn. invoke and chat print the conversation and run they used. A run that failed is the one most worth reading: invoke --trace puts its trace on stderr ahead of the error. Against an agent deployed before traces existed, invoke --trace still prints the reply, with a warning in place of the trace.

What a Trace Holds

Step	Recorded
`run`	How the run came in (`invoke`, `chat`, `web`, `sms`, `email`, `eval`), its status, the failure code when it failed, its duration, the total tokens and the number of tool calls.
`model`	The model, the step number, input, output and total tokens, the finish reason, and for a streamed call the time to its first output.
`tool`	The tool, `ok`, `error` or `denied`, the size in bytes of what it returned, the provider’s tool call id, and the harness’s step name for it (`tool:web_search:0`).
`approval`	The tool waiting on the approval, `pending` while it waits, then the decision (`approved` or `denied`) and the time waited. An approval that expires or is canceled closes with the run.
`deliver`	The channel the reply went out on, whether it was delivered, and the attempt when it took more than one.

A trace is metadata only. It never holds message text, a tool’s arguments or its result, or an error’s message: an error is recorded as its type, its code and its HTTP status, because a provider’s error body or a tool’s thrown message can carry a secret, such as a URL with a token. So a browser_fill value or an MCP server’s secret header never reaches a trace. Traces are kept in the conversation’s own store, next to its messages: the newest 50 runs, at most 200 steps each, the oldest going first. Recording is best effort; a step that cannot be written is dropped with one log line, and the run goes on. Phone calls are not traced. Under --json, a run’s trace is data.trace, { run, spans }, each span with id, parent, kind, name, start (epoch milliseconds), durationMs, status and attrs. The list is data.runs. eval reads the same trace for its tool and noTool checks.

Traces live in the agent and are read through the CLI only; they are not exported to an OpenTelemetry collector or a tracing service yet.

Get Started

Runtime Platform

Managed Harness

CLI

Reference

For AI Agents

What a Trace Holds

​What a Trace Holds

What a Trace Holds