run-ingestion

name	run-ingestion
description	Submit agent run data to agent-debugger via the ingestion API. Use when you need to understand the ingestion wire format, troubleshoot ingest errors, batch-submit steps, or integrate agent-debugger into a new language or framework. Triggers include "ingest API", "submit run data", "record steps", "POST ingest", "agent-debugger integration", or building an instrumentation library.

run-ingestion

Wire protocol for submitting agent run data to agent-debugger.

Overview

agent-debugger receives run data via HTTP POST requests to /api/ingest/*. All requests require a JSON body with Content-Type: application/json. When AGENT_INGEST_TOKEN is set, all requests must include Authorization: Bearer <token>.

Endpoints

POST /api/ingest/run

Start a new run. Returns a run_id used for all subsequent step submissions.

Request

{
  "id": "agent_run_abc123",     // optional - server auto-generates if omitted
  "name": "Ticket #9041",       // optional human name
  "agent": "support-agent-v2",  // required - identifies the agent
  "session_id": "sess_xyz",     // optional - groups related runs
  "metadata": {                 // optional - any JSON object
    "environment": "production",
    "version": "2.1.4"
  }
}

Response 201

{ "run_id": "agent_run_abc123", "status": "running" }

Errors

• 400 - missing required fields or invalid JSON
• 401 - missing or invalid bearer token
• 409 - run ID already exists (if ID was supplied)

---

POST /api/ingest/step

Submit a single step. Steps are ordered by step_index.

Request

{
  "run_id": "agent_run_abc123",   // required
  "type": "llm_call",             // required - see Step Types below
  "name": "gpt-4o",               // required - tool name or model name
  "input": { ... },               // required - JSON object
  "output": { ... },              // optional - JSON object
  "error": "timeout after 30s",  // optional - set if step errored
  "context_size": 4200,           // optional - token count
  "duration_ms": 1240,            // optional - step execution time
  "metadata": { ... }             // optional
}

Response 201

{ "step_id": "step_a1b2c3", "step_index": 0 }

Steps are appended in submission order. step_index is auto-incremented.

Errors

• 400 - invalid payload or unknown step type
• 404 - run_id not found
• 413 - payload exceeds AGENT_MAX_STEP_SIZE

---

POST /api/ingest/run/:id/complete

Mark a run as completed.

Request

{
  "total_tokens": 18420,    // optional - total token count across all llm_calls
  "duration_ms": 12400      // optional - total wall clock time
}

Response 200

{ "run_id": "agent_run_abc123", "status": "completed", "total_steps": 24 }

---

POST /api/ingest/run/:id/fail

Mark a run as failed.

Request

{
  "error": "TimeoutError: web_search did not respond within 30000ms",
  "duration_ms": 18200
}

Response 200

{ "run_id": "agent_run_abc123", "status": "failed" }

---

Step Types Reference

llm_call

A call to a language model.

{
  "type": "llm_call",
  "name": "gpt-4o",
  "input": {
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "What is the capital of France?" }
    ],
    "model": "gpt-4o",
    "temperature": 0
  },
  "output": {
    "role": "assistant",
    "content": "The capital of France is Paris."
  },
  "context_size": 80,
  "duration_ms": 420
}

tool_call

Invoking a tool as requested by the LLM.

{
  "type": "tool_call",
  "name": "web_search",
  "input": {
    "query": "recent AI model releases 2024",
    "max_results": 10
  },
  "duration_ms": 85
}

tool_result

Result returned from a tool execution.

{
  "type": "tool_result",
  "name": "web_search",
  "input": {
    "query": "recent AI model releases 2024"
  },
  "output": {
    "results": [
      { "title": "GPT-4o announced", "url": "...", "snippet": "..." }
    ]
  },
  "duration_ms": 12
}

sub_agent

Spawning a sub-agent run.

{
  "type": "sub_agent",
  "name": "summarizer-agent",
  "input": { "task": "Summarize the 5 search results" },
  "metadata": { "sub_run_id": "agent_run_sub_xyz" },
  "duration_ms": 4200
}

event

Any other notable event during the run.

{
  "type": "event",
  "name": "retrieved_documents",
  "input": { "message": "Retrieved 5 documents from vector store", "count": 5 },
  "duration_ms": 45
}

---

Batch Step Submission

Steps must be submitted sequentially (one at a time). There is no batch endpoint. Submit each step immediately after it completes to ensure ordering.

Input Field Conventions for Context Viewer

For llm_call steps, set input to an object with a messages array following the OpenAI chat format:

{
  "messages": [
    { "role": "system", "content": "..." },
    { "role": "user", "content": "..." },
    { "role": "assistant", "content": "...", "tool_calls": [...] },
    { "role": "tool", "tool_call_id": "...", "content": "..." }
  ]
}

The context viewer renders role colors (system=yellow, user=blue, assistant=green, tool=cyan) and the token usage bar based on context_size.

Authentication

When AGENT_INGEST_TOKEN is set on the server, all ingest requests must include:

Authorization: Bearer <your-token>

The token is stored encrypted in settings. Set it in the dashboard Settings page. Rotate it from the same page.

Ingest Token Security

The ingest token protects your agent run data from unauthorized submission. Use a strong random token (at least 32 characters). Do not commit it to source code.

Recommended: store it in your environment and reference via process.env.AGENT_INGEST_TOKEN or equivalent.