How to call your AI Agent using the Chat API

Overview

This guide shows how to call your agent directly over HTTP and stream responses using the Vercel AI SDK data stream format. It covers the exact endpoint, headers, request body, and the event stream response you should expect.

Endpoint

• Path (mounted by the Run API): /api/chat
• Method: POST
• Protocol: Server-Sent Events (SSE) encoded JSON, using Vercel AI SDK data-stream v2
• Content-Type (response): text/event-stream
• Response Header: x-vercel-ai-data-stream: v2

Authentication

Choose the authentication method:

See Authentication → Run API for more details.

Request Body Schema

{
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "conversationId": "optional-conversation-id"
}

Field Notes:

• messages — Must include at least one user message
• content — Can be a string or an object with parts for multi-part content
• conversationId — Optional; server generates one if omitted

Optional Headers

• x-emit-operations — Set to true to include detailed data operations in the response stream. Useful for debugging and monitoring agent behavior. See Data Operations for details.

Example cURL

When using an API key for auth:

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"
  }'

Response: Vercel AI SDK Data Stream (v2)

The response is an SSE stream of JSON events compatible with the Vercel AI SDK UI message stream. The server sets x-vercel-ai-data-stream: v2.

Event Types

Text Streaming Events

• text-start — Indicates a new text segment is starting
• text-delta — Carries the text content delta for the current segment
• text-end — Marks the end of the current text segment

Data Events

• data-component — Structured UI data emitted by the agent (for rich UIs)
• data-artifact — Artifact data emitted by tools/agents (documents, files, saved results)
• data-operation — Low-level operational events (agent lifecycle, completion, errors)
• data-summary — AI-generated status updates with user-friendly labels and contextual details

Example Stream (abbreviated)

: keep-alive

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

data: {"type":"text-delta","id":"1726247200-abc123","delta":"Hello! I can help with..."}

data: {"type":"data-summary","data":{"label":"Searching documentation","details":{"summary":"Looking for relevant information","progress":"25%"}}}

data: {"type":"text-delta","id":"1726247200-abc123","delta":" analyzing your query..."}

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

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

data: {"type":"data-component","id":"1726247200-abc123-0","data":{"type":"customer-info","name":"Ada","email":"ada@example.com"}}

data: {"type":"data-artifact","data":{"artifact_id":"art_abc","task_id":"task_xyz","summary":{"title":"Search Results"}}}

Data Event Details

data-operation Events

Low-level operational events with technical context. Common types include:

• agent_initializing — The agent runtime is starting
• agent_ready — Agent is ready and processing
• completion — The agent completed the task (includes agent ID and iteration count)
• error — Error information (also emitted as a top-level error event)

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

data-summary Events

AI-generated status updates designed for end-user consumption. Structure:

• label — User-friendly description (required)
• details — Optional structured/unstructured context data

{"type":"data-summary","data":{"label":"Processing search results","details":{"summary":"Found 12 relevant documents","itemsProcessed":12,"status":"analyzing"}}}

data-artifact Events

Saved documents, files, or structured results from tool executions:

{"type":"data-artifact","data":{"artifact_id":"art_123","task_id":"task_456","summary":{"title":"Weather Report","type":"document"}}}

data-component Events

Structured UI data for rich interface components:

{"type":"data-component","id":"comp_123","data":{"type":"chart","title":"Sales Data","chartData":[1,2,3]}}

Text Streaming Behavior

• For each text segment, the server emits text-start → text-delta → text-end
• The server avoids splitting content word-by-word; a segment is usually a coherent chunk
• Operational events are queued during active text emission and flushed shortly after to preserve ordering and readability

Error Responses

Streamed Errors

Errors are now delivered as data-operation events with unified structure:

{
  "type": "data-operation",
  "data": {
    "type": "error",
    "message": "Error description",
    "agent": "agent-id",
    "severity": "error",
    "code": "optional-error-code",
    "timestamp": 1640995200000
  }
}

Non-Streaming Errors

Validation failures and other errors return JSON with an appropriate HTTP status code.

HTTP Status Codes

• 200 — Stream opened successfully
• 401 — Missing/invalid authentication
• 404 — Agent not found
• 400 — Invalid request body/context
• 500 — Internal server error

Development Notes

• Default local base URL: http://localhost:3003
• Endpoint mounting in the server:
  • /api/chat → Vercel data stream (this page)
  • /v1/mcp → MCP JSON-RPC endpoint