How to call your AI Agent Graph via a Vercel AI SDK format API

Overview

This guide shows how to call your agent graph 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.

Tip

If you are building a React UI, consider our prebuilt components under React UI Components. This page is for low-level HTTP usage.

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

Note

Provide request context via HTTP headers only (validated against your Context Config). Do not include it in the JSON body. See Request context.

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" \
  -d '{
    "messages": [
      { "role": "user", "content": "What can you do?" }
    ],
    "conversationId": "chat-1234"
  }'

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 — Graph or 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