--- title: "Decision Traces" description: "Record and replay agent reasoning steps, tool calls, and outcomes — let agents learn from past decisions" canonical: "https://docs.ainative.studio/docs/zeromemory/decision-traces" last-updated: "2026-10-22T17:48:46.689Z" --- # Decision Traces Source: https://docs.ainative.studio/docs/zeromemory/decision-traces > Record and replay agent reasoning steps, tool calls, and outcomes — let agents learn from past decisions ## 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 `. --- ## 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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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:** ```json { "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. ```bash curl https://api.ainative.studio/api/v1/public/memory/v2/traces/trace-a1b2c3d4 \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "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:** ```json { "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:** ```json { "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. ```bash curl https://api.ainative.studio/api/v1/public/memory/v2/traces/tool_stats \ -H "Authorization: Bearer $TOKEN" ``` **Response:** ```json { "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 ```python 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 |