run-ingestion

# 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**
```json
{
  "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**
```json
{ "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**
```json
{
  "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**
```json
{ "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**
```json
{
  "total_tokens": 18420,    // optional - total token count across all llm_calls
  "duration_ms": 12400      // optional - total wall clock time
}
```

**Response 200**
```json
{ "run_id": "agent_run_abc123", "status": "completed", "total_steps": 24 }
```

---

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

Mark a run as failed.

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

**Response 200**
```json
{ "run_id": "agent_run_abc123", "status": "failed" }
```

---

## Step Types Reference

### llm_call

A call to a language model.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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:

```json
{
  "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.