Data Operations

Learn about data operations emitted by agents and how to use the x-emit-operations header to control their visibility.

Overview

Data operations are detailed, real-time events that provide visibility into what agents are doing during execution. They include agent reasoning, tool executions, transfers, delegations, and artifact creation. By default, these operations are hidden from end users to keep the interface clean, but they can be enabled for debugging and monitoring purposes.

The x-emit-operations Header

The x-emit-operations header controls whether data operations are included in the response stream. When set to true, the system will emit detailed operational events alongside the regular response content.

Usage

curl -N \
  -X POST "http://localhost:3003/api/chat" \
  -H "Authorization: Bearer $INKEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-emit-operations: true" \
  -d '{
    "messages": [
      { "role": "user", "content": "What can you do?" }
    ],
    "conversationId": "chat-1234"
  }'

CLI Usage

In the CLI, you can toggle data operations using the operations command:

# Start a chat session
inkeep chat

# Toggle data operations on/off
> operations
🔧 Emit operations: ON
Data operations will be shown during responses.

> operations
🔧 Emit operations: OFF
Data operations are hidden.

Data Operation Types

Agent Events

`agent_generate`

Emitted when an agent generates content — text, structured data, or a mix of both.

{
  "type": "data-operation",
  "data": {
    "type": "agent_generate",
    "label": "Agent search-agent generating response",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "parts": [
          {
            "type": "text",
            "content": "I found 5 relevant documents..."
          }
        ],
        "generationType": "text_generation"
      }
    }
  }
}

generationType values:

Value	Meaning
`text_generation`	The response is text only — no structured data components were emitted.
`object_generation`	The response is a structured object only — the agent emitted a data component that matches a `dataComponents` schema, with no accompanying prose.
`mixed_generation`	The response contains both text and one or more structured data components. Emitted when an agent configured with `dataComponents` also produces prose (for example, a reasoning prelude before a structured result, or narration alongside a data component).

data.parts[].type values:

Value	Payload fields	Notes
`text`	`content`	Prose emitted by the agent.
`data_component`	`data`	A structured data component matching one of the agent's `dataComponents` schemas.
`data_artifact`	`data`	A structured artifact (has both `artifactId` and `toolCallId` on `data`).
`tool_call`	`toolName`, `args`	Internal tool invocation (rare in `agent_generate`; more common in `agent_reasoning`).
`tool_result`	`toolName`, `result`	Internal tool result (rare in `agent_generate`; more common in `agent_reasoning`).

When generationType is mixed_generation, data.parts is ordered by emission: a text part may precede a data component, appear between components, or follow them. Consumers that render agent responses should iterate parts in order and render each entry according to its type.

`agent_reasoning`

Emitted when an agent is reasoning through a request or planning its approach.

{
  "type": "data-operation",
  "data": {
    "type": "agent_reasoning",
    "label": "Agent search-agent reasoning through request",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "parts": [
          {
            "type": "text",
            "content": "I need to search for information about..."
          }
        ]
      }
    }
  }
}

Tool Execution Events

`tool_call`

Emitted when an agent starts calling a tool or function.

{
  "type": "data-operation",
  "data": {
    "type": "tool_call",
    "label": "Tool call: search_documents",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "toolName": "search_documents",
        "args": {
          "query": "machine learning best practices",
          "limit": 10
        },
        "toolCallId": "call_abc123",
        "toolId": "tool_xyz789"
      }
    }
  }
}

Tool Approval Events

When a tool requires user approval, the tool_call event includes additional fields:

{
  "type": "data-operation",
  "data": {
    "type": "tool_call",
    "label": "Tool call: delete_user_data",
    "details": {
      "timestamp": 1726247200000,
      "subAgentId": "data-agent",
      "data": {
        "toolName": "delete_user_data",
        "input": {
          "userId": "user_123",
          "confirm": true
        },
        "toolCallId": "call_approval_xyz789",
        "needsApproval": true,
        "conversationId": "conv_abc123"
      }
    }
  }
}

Approval-specific fields:

needsApproval: true - Indicates this tool requires user approval before execution
conversationId - The conversation context for sending approval responses

See Tool approvals for complete configuration and integration details.

`tool_result`

Emitted when a tool execution completes (success or failure). Tool results can include text, structured data, or multimedia content such as images.

{
  "type": "data-operation",
  "data": {
    "type": "tool_result",
    "label": "Tool result: search_documents",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "toolName": "search_documents",
        "result": {
          "documents": [
            {
              "title": "ML Best Practices Guide",
              "url": "/docs/ml-guide",
              "relevance": 0.95
            }
          ]
        },
        "toolCallId": "call_abc123",
        "toolId": "tool_xyz789",
        "duration": 1250
      }
    }
  }
}

Error Example:

{
  "type": "data-operation",
  "data": {
    "type": "tool_result",
    "label": "Tool error: search_documents",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "toolName": "search_documents",
        "result": null,
        "toolCallId": "call_abc123",
        "toolId": "tool_xyz789",
        "duration": 500,
        "error": "API rate limit exceeded"
      }
    }
  }
}

Image Result Example:

{
  "type": "data-operation",
  "data": {
    "type": "tool_result",
    "label": "Tool result: generate_chart",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "analysis-agent",
      "data": {
        "toolName": "generate_chart",
        "result": {
          "image": "blob://v1/t_org123/media/p_proj456/conv/c_conv789/m_msg012/sha256-a1b2c3d4.png",
          "title": "Q4 Sales Performance"
        },
        "toolCallId": "call_xyz789",
        "toolId": "tool_chart123",
        "duration": 2100
      }
    }
  }
}

Note

The blob:// URI is an internal storage reference. When retrieved via the API or conversation history, these are automatically resolved to accessible media proxy URLs. See Images in Memory.

Agent Interaction Events

`transfer`

Emitted when control is transferred from one agent to another.

{
  "type": "data-operation",
  "data": {
    "type": "transfer",
    "label": "Agent transfer: search-agent → analysis-agent",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "fromSubAgent": "search-agent",
        "targetAgent": "analysis-agent",
        "reason": "Specialized analysis required",
        "context": {
          "searchResults": "...",
          "userQuery": "..."
        }
      }
    }
  }
}

`delegation_sent`

Emitted when an agent delegates a task to another agent.

{
  "type": "data-operation",
  "data": {
    "type": "delegation_sent",
    "label": "Task delegated: coordinator-agent → search-agent",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "coordinator-agent",
      "data": {
        "delegationId": "deleg_xyz789",
        "fromSubAgent": "coordinator-agent",
        "targetAgent": "search-agent",
        "taskDescription": "Search for information about machine learning",
        "context": {
          "priority": "high",
          "deadline": "2024-01-15T10:00:00Z"
        }
      }
    }
  }
}

`delegation_returned`

Emitted when a delegated task is completed and returned.

{
  "type": "data-operation",
  "data": {
    "type": "delegation_returned",
    "label": "Task completed: search-agent → coordinator-agent",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "search-agent",
      "data": {
        "delegationId": "deleg_xyz789",
        "fromSubAgent": "search-agent",
        "targetAgent": "coordinator-agent",
        "result": {
          "status": "completed",
          "documents": [...],
          "summary": "Found 5 relevant documents"
        }
      }
    }
  }
}

Artifact Events

`artifact_saved`

Emitted when an agent creates or saves an artifact (document, chart, file, etc.).

{
  "type": "data-operation",
  "data": {
    "type": "artifact_saved",
    "label": "Artifact saved: chart",
    "details": {
      "timestamp": 1726247200000,
      "agentId": "analysis-agent",
      "data": {
        "artifactId": "art_123456",
        "taskId": "task_789",
        "toolCallId": "tool_abc123",
        "artifactType": "chart",
        "summaryData": {
          "title": "Sales Performance Q4 2023",
          "type": "bar_chart"
        },
        "fullData": {
          "chartData": [...],
          "config": {...}
        },
        "metadata": {
          "createdBy": "analysis-agent",
          "version": "1.0"
        }
      }
    }
  }
}

Field notes:

summaryData — contains the artifact's preview fields (those marked inPreview: true in the schema). These are available immediately in the agent's context and streamed to clients.
fullData — contains all remaining non-preview fields. This data is persisted in storage and retrievable on demand.

See Artifact Components for how to define preview and non-preview fields in your artifact schemas.

System Events

`agent_initializing`

Emitted when the agent runtime is starting up.

{
  "type": "data-operation",
  "data": {
    "type": "agent_initializing",
    "details": {
      "sessionId": "session_abc123",
      "agentId": "graph_xyz789"
    }
  }
}

`completion`

Emitted when an agent completes its task.

{
  "type": "data-operation",
  "data": {
    "type": "completion",
    "details": {
      "agent": "search-agent",
      "iteration": 1
    }
  }
}

`error`

Emitted when an error occurs during execution.

{
  "type": "data-operation",
  "data": {
    "type": "error",
    "message": "Tool execution failed: API rate limit exceeded",
    "agent": "search-agent",
    "severity": "error",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": 1726247200000
  }
}

Example: Complete Request with Data Operations

Here's a complete example showing a request with data operations enabled:

curl -N \
  -X POST "http://localhost:3003/api/chat" \
  -H "Authorization: Bearer $INKEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-emit-operations: true" \
  -d '{
    "messages": [
      { "role": "user", "content": "Create a sales report for Q4" }
    ],
    "conversationId": "chat-1234"
  }'

Response Stream:

data: {"type":"agent_initializing","details":{"sessionId":"session_abc123","agentId":"graph_xyz789"}}

data: {"type":"data-operation","data":{"type":"agent_reasoning","label":"Agent coordinator-agent reasoning through request","details":{"timestamp":1726247200000,"agentId":"coordinator-agent","data":{"parts":[{"type":"text","content":"I need to create a sales report for Q4. This will require gathering data and generating a chart."}]}}}}

data: {"type":"data-operation","data":{"type":"tool_call","label":"Tool call: get_sales_data","details":{"timestamp":1726247200000,"agentId":"coordinator-agent","data":{"toolName":"get_sales_data","args":{"quarter":"Q4","year":"2023"},"toolCallId":"call_abc123","toolId":"tool_xyz789"}}}}

data: {"type":"data-operation","data":{"type":"tool_result","label":"Tool result: get_sales_data","details":{"timestamp":1726247200000,"agentId":"coordinator-agent","data":{"toolName":"get_sales_data","result":{"sales":[...]},"toolCallId":"call_abc123","toolId":"tool_xyz789","duration":850}}}}

data: {"type":"data-artifact","data":{ ... }}

data: {"type":"data-operation","data":{"type":"artifact_saved","label":"Artifact saved: chart","details":{"timestamp":1726247200000,"agentId":"coordinator-agent","data":{"artifactId":"art_123456","artifactType":"chart","summaryData":{"title":"Q4 Sales Report"}}}}}

data: {"type":"text-start","id":"1726247200-abc123"}

data: {"type":"text-delta","id":"1726247200-abc123","delta":"I've created a comprehensive Q4 sales report..."}

data: {"type":"text-end","id":"1726247200-abc123"}

data: {"type":"completion","details":{"agent":"coordinator-agent","iteration":1}}

This provides complete visibility into the agent's execution process, from initialization through reasoning, tool execution, artifact creation, and final response generation.

On this page