Reasoning Traces

Every agent execution produces a reasoning trace — a complete record of every thought, action, input, and observation across all iterations. Traces are stored persistently and are queryable via API.

Trace Format

Each iteration in the trace contains:

json

{
  "iteration": 1,
  "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`	Sequence number (1-indexed)
`timestamp`	When this iteration executed
`thought`	The agent's reasoning — why it chose this 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 complete trace is an array of these objects, one per iteration, plus metadata about the overall run.

Accessing Traces

Get Full Trace

bash

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

GET/agents/:id/trace

Returns the complete reasoning trace for an agent run.

Get Status with Trace

Include the trace inline with the status response:

bash

curl https://apisvr.tryhyphen.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 full reasoning 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": 1, "thought": "...", "action": "lookup_ticket", "..." : "..." },
    { "iteration": 2, "thought": "...", "action": "check_billing", "..." : "..." },
    { "iteration": 3, "thought": "...", "action": "process_refund", "..." : "..." },
    { "iteration": 4, "thought": "...", "action": "__complete__", "..." : "..." }
  ]
}

Querying Traces

List Agent Runs

Filter by status to find runs that need review:

bash

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

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

# Recent runs with pagination
curl "https://apisvr.tryhyphen.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

Reasoning traces serve critical compliance and governance functions:

Regulatory audit. When a regulator asks "why was this transaction flagged?" you can show the exact reasoning chain — what the agent checked, what it found, and why it made its decision.

Decision explainability. Every agent decision has a thought field explaining the reasoning. This satisfies explainability requirements in regulated industries (financial services, healthcare, insurance).

Process verification. Traces prove that required steps were followed. If the process requires sanctions screening before account opening, the trace shows the screening tool was called and the result was checked.

Incident investigation. When something goes wrong, the trace shows exactly where and why. You can see the agent's last thought, which tool failed, and what observation led to an incorrect decision.

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

Secrets that appear in reasoning traces are automatically redacted before storage. This includes:

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

If an agent's thought or observation contains a secret value (because the LLM included it in its reasoning or a tool returned it), the redaction layer strips it:

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": { "..." : "..." }
  }
}

Redaction happens at storage time. The actual secret is used during execution but never persisted in the trace.

Trace Storage

Traces are stored in the database alongside the agent run record. They are scoped per organization (same multi-tenant isolation as all other data) and persist indefinitely unless explicitly deleted.

For high-volume deployments, configure trace retention policies to manage storage. The include_reasoning_trace property on the loop can be set to false to disable trace storage for non-critical agents — though this is not recommended for production workflows that may need audit review.

→ Next: Deployment Patterns