Reasoning Traces

An agent trace records the model-provided rationale, selected tool, tool input, and resulting observation for each action. It gives developers and reviewers a practical account of what the agent did during a run.

Trace Format

Each iteration in the trace contains:

json

{
  "iteration": 0,
  "timestamp": "2026-02-01T10:30:01Z",
  "thought": "I need to look up the ticket details to understand the customer's issue.",
  "action": "lookup_ticket",
  "action_input": {
    "ticket_id": "TK-12345"
  },
  "observation": {
    "subject": "Billing Error: Double Charge",
    "status": "open",
    "priority": "high",
    "customer_id": "cust-789",
    "created_at": "2026-01-31T14:22:00Z"
  },
  "success": true
}

Field	Description
`iteration`	Zero-based iteration number
`timestamp`	When this iteration executed
`thought`	Model-provided rationale for the selected action
`action`	Which tool was called
`action_input`	Parameters passed to the tool (sensitive fields automatically redacted)
`observation`	The tool's response (truncated for large payloads)
`success`	Whether the tool call succeeded

A trace is an array of action records plus lifecycle metadata. Parallel tool calls can produce more than one record for the same iteration.

Accessing Traces

Get Full Trace

bash

curl https://your-hyphen.example.com/agents/{agentRunId}/trace \
  -H "X-Org-Id: acme-corp"

GET/agents/:id/trace

Returns the complete recorded trace for an agent run.

Get Status with Trace

Include the trace inline with the status response:

bash

curl https://your-hyphen.example.com/agents/{agentRunId}/status?include_trace=true \
  -H "X-Org-Id: acme-corp"

GET/agents/:id/status?include_trace=true

Returns agent status plus the recorded agent trace.

Response

json

{
  "agent_run_id": "agent-123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "objective": "Process support ticket TK-12345",
  "iterations": 4,
  "final_answer": "Ticket resolved. Refund of $49.99 processed, confirmation email sent.",
  "confidence": 0.95,
  "triggered_runs": [],
  "created_at": "2026-02-01T10:30:00Z",
  "completed_at": "2026-02-01T10:30:12Z",
  "error_details": null,
  "reasoning_trace": [
    { "iteration": 0, "thought": "...", "action": "lookup_ticket", "success": true },
    { "iteration": 1, "thought": "...", "action": "check_billing", "success": true },
    { "iteration": 2, "thought": "...", "action": "process_refund", "success": true },
    { "iteration": 3, "thought": "...", "action": "__complete__", "success": true }
  ]
}

Querying Traces

List Agent Runs

Filter by status to find runs that need review:

bash

# All paused agents (waiting for human input)
curl "https://your-hyphen.example.com/agents?status=paused" \
  -H "X-Org-Id: acme-corp"

# All failed agents
curl "https://your-hyphen.example.com/agents?status=failed" \
  -H "X-Org-Id: acme-corp"

# Recent runs with pagination
curl "https://your-hyphen.example.com/agents?limit=20&offset=0" \
  -H "X-Org-Id: acme-corp"

:::api GET /agents?status={status} List agent runs filtered by status: running, paused, completed, failed. :::

Compliance Use Cases

Agent traces provide evidence that teams can use in governance and compliance programs:

Audit review. When a reviewer asks why a transaction was flagged, the trace shows the recorded rationale, tools called, inputs supplied, and observations returned.

Decision review. The thought field records the model's stated rationale for choosing an action. Teams can review it alongside deterministic evidence and policy checks.

Process evidence. A trace can show that a required tool was called and what it returned. Pair it with workflow evidence and your control tests when demonstrating that a policy was followed.

Incident investigation. When something goes wrong, the trace helps identify the last recorded rationale, the tool involved, and the observation available to the agent.

Human oversight documentation. When an agent pauses for human input, the trace records both the agent's question and the human's response. This documents the human-in-the-loop review for audit purposes.

Secret redaction

Hyphen redacts recognized sensitive field names and common secret shapes from recorded action inputs and observations. This includes:

API keys and tokens referenced via orgconfig:
OAuth access tokens and refresh tokens
Database connection strings
Any value matching common secret patterns

Redaction provides an extra layer of protection for recorded action data:

json

{
  "thought": "I'll call the API with the authentication token.",
  "action": "fetch_data",
  "action_input": {
    "url": "https://api.example.com/data",
    "token": "[REDACTED]"
  },
  "observation": {
    "status": 200,
    "data": { "...": "..." }
  }
}

Keep credentials in organization configuration and pass them through orgconfig: references. Do not place credentials in objectives, prompts, or ordinary business fields.

Trace storage

Trace data is stored with the agent run and scoped to its organization. Set include_reasoning_trace to false when the loop result should omit the action trace. Retention and export should follow the data policy for your deployment.

→ Next: Deployment Patterns