Decision Traces

Decision Traces

Decision Traces let agents record their reasoning process and learn from past decisions. Each trace captures the thought chain, tool calls, and outcome for a task — and can be recalled later via semantic search.

Base path: https://api.ainative.studio/api/v1/public/memory/v2/traces

All endpoints require Authorization: Bearer <token>.

---

How It Works

POST /traces/start          → Begin recording (get trace_id)
POST /traces/{id}/step      → Record a reasoning step
POST /traces/{id}/tool_call → Record a tool invocation
POST /traces/{id}/complete  → Close with outcome + success flag
POST /traces/recall         → Find similar past traces

---

POST /traces/start

Begin recording a decision trace. Returns a trace_id to reference in subsequent calls.

Request:

{
  "task": "Find the best Italian restaurants near the conference venue",
  "session_id": "session-abc123",
  "triggered_by_memory_id": "mem_xyz"
}

Field	Type	Required	Description
task	string	yes	What the agent is trying to accomplish
session_id	string	yes	Session identifier
triggered_by_memory_id	string	no	Memory ID that triggered this trace

Response:

{
  "trace_id": "trace-a1b2c3d4",
  "task": "Find the best Italian restaurants near the conference venue",
  "status": "active",
  "created_at": "2026-04-23T12:00:00Z"
}

---

POST /traces/{trace_id}/step

Record a reasoning step — the agent's thought and the action it chose.

Request:

{
  "thought": "I need to search for Italian restaurants. I'll use the web_search tool with a location-aware query.",
  "action": "call web_search with query='Italian restaurants near Moscone Center SF'",
  "observations": ["Found 15 results", "Top 3 have 4.5+ star ratings"]
}

Field	Type	Required	Description
thought	string	yes	Agent's reasoning at this step
action	string	yes	Action decided upon
observations	string[]	no	Environment observations

Response:

{
  "step_id": "step-001",
  "trace_id": "trace-a1b2c3d4",
  "created_at": "2026-04-23T12:00:05Z"
}

---

POST /traces/{trace_id}/tool_call

Record a tool invocation within the current trace step.

Request:

{
  "tool_name": "web_search",
  "arguments": {"query": "Italian restaurants near Moscone Center SF", "limit": 10},
  "result": {"results": ["Trattoria Milano", "Perbacco", "Coqueta"]},
  "duration_ms": 420,
  "status": "success",
  "memory_id": null,
  "step_id": "step-001"
}

Field	Type	Required	Description
tool_name	string	yes	Tool that was called
arguments	object	yes	Arguments passed to the tool
result	any	yes	Return value from the tool
duration_ms	int	yes	Execution time in milliseconds
status	string	yes	success, error, or timeout
memory_id	string	no	Memory ID used/created by this call
step_id	string	no	Step to attach to (defaults to latest)

---

POST /traces/{trace_id}/complete

Close the trace with an outcome summary and success flag. Required to make the trace available for semantic recall.

Request:

{
  "outcome": "Found top 3 Italian restaurants with ratings above 4.5 and provided directions to each.",
  "success": true
}

---

GET /traces/{trace_id}

Fetch a complete trace with all steps and tool calls.

curl https://api.ainative.studio/api/v1/public/memory/v2/traces/trace-a1b2c3d4 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "trace_id": "trace-a1b2c3d4",
  "task": "Find Italian restaurants near conference venue",
  "status": "completed",
  "success": true,
  "outcome": "Found top 3 restaurants...",
  "steps": [
    {
      "step_id": "step-001",
      "thought": "I need to search for Italian restaurants...",
      "action": "call web_search",
      "observations": ["Found 15 results"],
      "tool_calls": [
        {
          "tool_name": "web_search",
          "duration_ms": 420,
          "status": "success"
        }
      ]
    }
  ],
  "created_at": "2026-04-23T12:00:00Z",
  "completed_at": "2026-04-23T12:00:08Z"
}

---

POST /traces/recall

Find past decision traces semantically similar to a query. Enables agents to learn from experience.

Request:

{
  "query": "find restaurants near a venue",
  "success_only": true,
  "limit": 5
}

Field	Type	Default	Description
query	string	required	Natural language task description
success_only	bool	true	Return only successful traces
limit	int	10	1-50 max results

Response:

{
  "results": [
    {
      "trace_id": "trace-a1b2c3d4",
      "task": "Find Italian restaurants near conference venue",
      "outcome": "Found top 3 restaurants with 4.5+ ratings",
      "similarity": 0.91,
      "tool_sequence": ["web_search", "maps_api"],
      "success": true,
      "created_at": "2026-04-23T12:00:00Z"
    }
  ],
  "count": 1
}

---

GET /traces/tool_stats

Aggregate statistics on tool usage across all traces. Useful for identifying unreliable or slow tools.

curl https://api.ainative.studio/api/v1/public/memory/v2/traces/tool_stats \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "tool_stats": [
    {
      "tool_name": "web_search",
      "call_count": 142,
      "success_rate": 0.97,
      "avg_duration_ms": 380,
      "min_duration_ms": 120,
      "max_duration_ms": 2100
    }
  ],
  "count": 8
}

---

Full Example

import requests

TOKEN = "your-api-key"
BASE = "https://api.ainative.studio/api/v1/public/memory/v2/traces"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

## 1. Start a trace
trace = requests.post(f"{BASE}/start", headers=H, json={
    "task": "Summarize the latest AI safety research papers",
    "session_id": "session-001"
}).json()
trace_id = trace["trace_id"]

## 2. Record a reasoning step
step = requests.post(f"{BASE}/{trace_id}/step", headers=H, json={
    "thought": "I should search ArXiv for recent safety papers from the last 30 days.",
    "action": "call web_fetch with url='arxiv.org/search/?query=ai+safety'",
}).json()

## 3. Record the tool call
requests.post(f"{BASE}/{trace_id}/tool_call", headers=H, json={
    "tool_name": "web_fetch",
    "arguments": {"url": "https://arxiv.org/search/?query=ai+safety&start=0"},
    "result": {"papers": ["Constitutional AI", "Scalable Oversight", "RLHF survey"]},
    "duration_ms": 650,
    "status": "success",
    "step_id": step["step_id"]
})

## 4. Complete the trace
requests.post(f"{BASE}/{trace_id}/complete", headers=H, json={
    "outcome": "Retrieved 12 recent AI safety papers and summarized key themes.",
    "success": True
})

## 5. Later — recall similar traces to reuse the approach
similar = requests.post(f"{BASE}/recall", headers=H, json={
    "query": "summarize research papers on a topic",
    "success_only": True,
    "limit": 3
}).json()
print(similar["results"][0]["tool_sequence"])  # ['web_fetch', ...]

---

Endpoint Summary

Method	Path	Description
POST	/traces/start	Start a new trace
POST	/traces/{id}/step	Add a reasoning step
POST	/traces/{id}/tool_call	Record a tool call
POST	/traces/{id}/complete	Complete the trace
GET	/traces/{id}	Fetch full trace
POST	/traces/recall	Semantic trace search
GET	/traces/tool_stats	Aggregate tool statistics