agent-trace

🔍 Trace API Reference

Reasoning provenance for AI agents. Store the why behind decisions — not just what happened, but how it was reasoned. Retrieve, search semantically, and reconstruct full reasoning chains.

✅ Live — agent-trace is available now. Create a project to get your API key.

🔑 Base URL: https://api.agenttool.dev · All endpoints require Authorization: Bearer YOUR_API_KEY

Why reasoning provenance?

When an agent generates output, the thinking that led to it is discarded. Future sessions see the conclusion but not the reasoning chain. This breaks:

Continuity — "why did I do X?" becomes unanswerable
Debugging — can't tell if a decision was correct or a lucky guess
Multi-agent trust — Agent B can't audit Agent A's reasoning
Self-improvement — hard to improve a decision you can't reconstruct

agent-trace gives every decision a permanent, searchable record — distinct from memory (what happened) this is reasoning provenance (why it happened).

Store a Trace

POST /v1/traces

Store a reasoning record. Returns a trace_id for future retrieval.

Request Body

Field	Type	Required	Description
`decision.type`	string	✓	`decision`, `tool_call`, `plan`, `verification`, `other`
`decision.summary`	string	✓	Short summary of what was decided
`decision.output_ref`	string		Reference to the output this trace explains
`reasoning.observations`	string[]	✓	What the agent observed/read that informed the decision
`reasoning.conclusion`	string	✓	What was concluded or decided
`reasoning.hypothesis`	string		Alternative hypothesis considered
`reasoning.confidence`	float		0.0–1.0 confidence in the conclusion
`reasoning.alternatives_considered`	object[]		Other paths considered: `[{"option": "..."}]`
`context.files_read`	string[]		Files or sources read during reasoning
`context.key_facts`	string[]		Key facts extracted during reasoning
`agent_id`	string		Agent identifier for filtering
`session_id`	string		Session identifier for grouping related traces
`tags`	string[]		Tags for filtering
`parent_trace_id`	string		Parent trace_id for chain building

curl

curl -X POST https://api.agenttool.dev/v1/traces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": {
      "type": "decision",
      "summary": "User approaching Free tier daily limit — suggest upgrade"
    },
    "reasoning": {
      "observations": [
        "User asked about tier pricing",
        "Checked subscription: Free tier, 87/100 ops used today"
      ],
      "conclusion": "User is on Free tier and approaching daily limit.",
      "confidence": 0.95
    },
    "tags": ["billing", "upgrade"],
    "agent_id": "support-agent"
  }'

Response · 201

{
  "trace_id": "tr_a1b2c3d4e5f6",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

SDK

// TypeScript
const trace = await at.traces.store({
  observations: [
    "User asked about tier pricing",
    "Checked subscription: Free tier, 87/100 ops used today",
  ],
  conclusion: "User approaching limit — suggest upgrade",
  confidence: 0.95,
  tags: ["billing"],
})

SDK

# Python
trace = at.traces.store(
    observations=[
        "User asked about tier pricing",
        "Checked subscription: Free tier, 87/100 ops used today",
    ],
    conclusion="User approaching limit — suggest upgrade",
    confidence=0.95,
    tags=["billing"],
)

Get a Trace

GET /v1/traces/{trace_id}

Retrieve a specific trace by its trace_id.

curl

curl https://api.agenttool.dev/v1/traces/tr_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Traces

POST /v1/traces/search

Search traces by semantic similarity. Uses vector embeddings to find reasoning records similar to your query.

Field	Type	Required	Description
`query`	string	✓	Natural language search query
`limit`	integer		Max results (default 10)
`agent_id`	string		Filter by agent_id
`session_id`	string		Filter by session_id
`tag`	string		Filter by tag

curl

curl -X POST https://api.agenttool.dev/v1/traces/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "billing and upgrade decisions", "limit": 5}'

Response · 200

[
  {
    "trace": { "trace_id": "tr_a1b2c3", "conclusion": "User approaching limit...", "confidence": 0.95, ... },
    "score": 0.89
  }
]

SDK

const results = await at.traces.search("billing decisions", { limit: 5 })
for (const { trace, score } of results) {
  console.log(score.toFixed(2), trace.conclusion)
}

Get Reasoning Chain

GET /v1/traces/chain/{parent_trace_id}

Retrieve a complete reasoning chain — the parent trace and all its children. Useful for reconstructing multi-step decision sequences.

curl

curl https://api.agenttool.dev/v1/traces/chain/tr_a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response · 200

{
  "parent": { "trace_id": "tr_a1b2c3", ... },
  "children": [
    { "trace_id": "tr_d4e5f6", "parent_trace_id": "tr_a1b2c3", ... }
  ],
  "depth": 1
}

Delete a Trace

DELETE /v1/traces/{trace_id}

Delete a trace. Returns 204 No Content on success.

SDK Quick Reference

📦 Install: pip install agenttool-sdk or npm install @agenttool/sdk

TypeScript / JavaScript

import { AgentTool } from "@agenttool/sdk"
const at = new AgentTool()  // reads AT_API_KEY from env

// Store a reasoning trace
const trace = await at.traces.store({
  observations: ["read file x", "found pattern y"],
  conclusion: "apply fix z",
  decision_type: "tool_call",
  tags: ["bugfix"],
})

// Search past reasoning
const results = await at.traces.search("how did I fix the auth bug?")

// Get reasoning chain
const chain = await at.traces.chain(trace.trace_id)

Python

from agenttool import AgentTool
at = AgentTool()  # reads AT_API_KEY from env

# Store a reasoning trace
trace = at.traces.store(
    observations=["read file x", "found pattern y"],
    conclusion="apply fix z",
    decision_type="tool_call",
    tags=["bugfix"],
)

# Search past reasoning
results = at.traces.search("how did I fix the auth bug?")

# Get reasoning chain
chain = at.traces.chain(trace.trace_id)

Use Cases

🐛 Debugging
Reconstruct exactly why an agent made a wrong decision. Search by session, agent, or tag to find the relevant trace.

🤝 Multi-agent trust
Agent B can verify Agent A's reasoning before acting on its conclusions. Link traces across agents with parent_trace_id.

📈 Self-improvement
Agents search their own past reasoning to avoid repeating mistakes and build on successful patterns.

📋 Audit trails
Every decision gets a timestamped, signed record. Human reviewers can audit reasoning post-hoc.