> ## Documentation Index > Fetch the complete documentation index at: https://docs.langdock.com/llms.txt > Use this file to discover all available pages before exploring further. # Agents Completions API > Creates a model response for a given Agent using Vercel AI SDK compatible format. **⚠️ Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`/api/public`** Creates a model response for a given agent ID, or pass in an Agent configuration that should be used for your request. This endpoint uses the Vercel AI SDK compatible message format for seamless integration with modern AI applications. To share an agent with an API key, follow [this guide](/en/developer/agents-api/agent-api-guide) **Vercel AI SDK Compatible**: This endpoint uses the Vercel AI SDK's UIMessage format, making it compatible with the `useChat` hook and other Vercel AI SDK features. **Using MCP:** You can also access your agents via the [Langdock MCP Server](/en/using-langdock/guides/integrations/mcp/langdock-agent-mcp-server), which lets MCP-compatible AI clients call your agents directly. ## Base URL ``` https://api.langdock.com/agent/v1/chat/completions ``` ## Request Parameters | Parameter | Type | Required | Description | | --------------------- | ------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | One of agentId/agent required | ID of an existing agent to use | | `agent` | object | One of agentId/agent required | Configuration for a temporary agent | | `messages` | array | Yes | Array of UIMessage objects (Vercel AI SDK format) | | `stream` | boolean | No | Enable streaming responses (default: false) | | `output` | object | No | Structured output format specification | | `maxSteps` | integer | No | Maximum number of tool steps (1-20) | | `imageResponseFormat` | string | No | Response format for agent-generated images. `"url"` returns a signed URL, `"b64_json"` returns base64-encoded image data. | ## Message Format (Vercel AI SDK UIMessage) The Agents API uses the Vercel AI SDK's UIMessage format for maximum compatibility with modern AI frameworks. ### UIMessage Structure Each message in the `messages` array should contain: ```typescript theme={null} interface UIMessage { id: string; // Unique identifier for this message role: 'system' | 'user' | 'assistant'; parts: MessagePart[]; // Array of message parts metadata?: { // Optional metadata attachments?: string[]; // Array of attachment UUIDs }; } ``` ### Message Part Types **User message parts** (for sending): | Type | Fields | Description | | ------ | ----------------------------------------------------------------------- | --------------------- | | `text` | `type: "text"`, `text: string` | Plain text content | | `file` | `type: "file"`, `mediaType: string`, `url: string`, `filename?: string` | Inline file reference | **Agent message parts** (returned in responses — include in conversation history when sending follow-up messages): | Type | Key Fields | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `text` | `type: "text"`, `text: string` | Text response | | `reasoning` | `type: "reasoning"`, `text: string` | Model reasoning / chain-of-thought | | `tool-{name}` | `type: "tool-{name}"`, `toolCallId: string`, `state: "input-streaming" \| "input-available" \| "output-available" \| "output-error"`, `input?: any`, `output?: any`, `errorText?: string` | Tool call and result | | `source-url` | `type: "source-url"`, `sourceId: string`, `url: string`, `title?: string` | Web source reference | | `source-document` | `type: "source-document"`, `sourceId: string`, `mediaType: string`, `title: string`, `filename?: string` | Document source reference | ### Example Messages #### User Message with Text ```javascript theme={null} { id: "msg_1", role: "user", parts: [ { type: "text", text: "Hello, how are you?" } ] } ``` #### User Message with Attachment ```javascript theme={null} { id: "msg_2", role: "user", parts: [ { type: "text", text: "Please analyze this document" } ], metadata: { attachments: ["550e8400-e29b-41d4-a716-446655440000"] } } ``` To attach files to a message, upload them via the [Upload Attachment API](/en/developer/agents-api/upload-attachments) and reference the returned UUIDs in the message's `metadata.attachments` array. Do not use `type: "file"` parts for uploaded attachments — that format is reserved for inline file references (e.g., data URIs). #### Agent Message with Tool Call ```javascript theme={null} { id: "msg_3", role: "assistant", parts: [ { type: "tool-webSearch", toolCallId: "call_123", state: "output-available", input: { query: "latest news" }, output: { /* search results */ } } ] } ``` ## Agent Configuration When creating a temporary agent using the `agent` parameter, you can specify: * `name` - Name of the agent (max 64 chars) * `instructions` - System instructions (max 16384 chars) * `description` - Optional description (max 256 chars) * `temperature` - Temperature between 0-1 * `model` - Model ID to use (see [Available Models](/en/developer/agents-api/agent-models) for options) * `capabilities` - Enable features like web search, data analysis, image generation, canvas * `knowledgeFolderIds` - IDs of knowledge folders to use * `attachmentIds` - Array of UUID strings identifying attachments to use You can retrieve a list of available models using the [Models API](/en/developer/agents-api/agent-models). The inline agent configuration field names differ from the [Create](/en/developer/agents-api/agent-create) and [Update](/en/developer/agents-api/agent-update) Agent APIs. In particular, this endpoint uses `instructions` (plural) and `temperature`, while the CRUD endpoints use `instruction` (singular) and `creativity`. The completions endpoint also accepts a nested `capabilities` object, while the CRUD endpoints use flat boolean fields. `attachmentIds` in the inline agent configuration is currently not functional — the agent will not be able to read the attached files. Instead, use `metadata.attachments` on individual messages to reference uploaded files per-message, or create a persistent agent with the `attachments` field via the [Create Agent API](/en/developer/agents-api/agent-create). ## Using Tools via API When an agent has tools configured (called "Actions" in the Langdock UI), it will automatically use them to respond to API requests when appropriate. The connection must be set to "preselected connection" (shared with other users) for tool authentication to work. Preselected connection setting in agent configuration Tools with **"Require human confirmation"** enabled do not work via API—they require manual approval in the Langdock UI. To use a tool via API, disable this setting in the agent configuration. ## Structured Output You can specify a structured output format using the optional `output` parameter: | Field | Type | Description | | -------- | ----------------------------- | -------------------------------------------------------------- | | `type` | "object" \| "array" \| "enum" | The type of structured output | | `schema` | object | JSON Schema definition for the output (for object/array types) | | `enum` | string\[] | Array of allowed values (for enum type) | The `output` parameter behavior depends on the specified type: * `type: "object"` with no schema: Forces the response to be a single JSON object (no specific structure) * `type: "object"` with schema: Forces the response to match the provided JSON Schema * `type: "array"` with schema: Forces the response to be an array of objects matching the provided schema * `type: "enum"`: Forces the response to be one of the values specified in the `enum` array You can use tools like [easy-json-schema](https://easy-json-schema.github.io/) to generate JSON Schemas from example JSON objects. ## Streaming Responses When `stream` is set to `true`, the API returns a stream using the Vercel AI SDK streaming format, compatible with the `useChat` hook and other Vercel AI SDK features. Non-streaming requests are terminated with an HTTP 524 error after 100 seconds. If your agent runs tools, generates long responses, or uses slower models, requests can exceed this limit. Set `stream: true` to keep the connection open and avoid timeouts. ### Using with Vercel AI SDK useChat Hook ```typescript theme={null} 'use client'; import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat({ api: 'https://api.langdock.com/agent/v1/chat/completions', headers: { 'Authorization': `Bearer ${process.env.NEXT_PUBLIC_LANGDOCK_API_KEY}` }, body: { agentId: 'your-agent-id' } }); return (
{messages.map(m => (
{m.role === 'user' ? 'User: ' : 'AI: '} {m.content}
))}
); } ``` ### Manual Stream Handling ```javascript theme={null} const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ agentId: 'agent_123', messages: [ { id: 'msg_1', role: 'user', parts: [{ type: 'text', text: 'Hello' }] } ], stream: true }), }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); console.log(chunk); // Process streaming chunks } ``` ## Obtaining Attachment IDs To use attachments in your agent conversations, first upload the files using the [Upload Attachment API](/en/developer/agents-api/upload-attachments). This returns an `attachmentId` (UUID) for each file. You can then use attachments in two ways: 1. **Per-message** (recommended): Include the attachment UUIDs in the message's `metadata.attachments` array. This lets you reference different files in different messages within the same conversation. 2. **Agent-level**: Include the UUIDs in the `attachments` array when [creating](/en/developer/agents-api/agent-create) or [updating](/en/developer/agents-api/agent-update) a persistent agent. All messages sent to that agent will have access to these files. ## Response Format The API returns a JSON object containing a `messages` array with the agent's response: ```typescript theme={null} interface CompletionResponse { messages: Array<{ id: string; role: "assistant"; content: string; }>; // Structured output - included when requested output?: object | array | string; } ``` ### Standard Response The response contains a `messages` array. Each message has: * `id` - Unique identifier for the message * `role` - Always `"assistant"` for completion responses * `content` - The agent's text response as a plain string ### Structured Output When the request includes an `output` parameter, the response will automatically include an `output` field containing the formatted structured data. The type of this field depends on the requested output format: * If `output.type` was "object": Returns a JSON object (with schema validation if schema was provided) * If `output.type` was "array": Returns an array of objects matching the provided schema * If `output.type` was "enum": Returns a string matching one of the provided enum values ## Examples ### Using an Existing Agent with Attachment ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agentId: "agent_123", messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "Can you analyze this document for me?" } ], metadata: { attachments: ["550e8400-e29b-41d4-a716-446655440000"] } } ] }) } ); const data = await response.json(); const responseText = data.messages[0].content; console.log(responseText); ``` ### Using a Temporary Agent Configuration ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agent: { name: "Document Analyzer", instructions: "You are a helpful agent who analyzes documents and answers questions about them", temperature: 0.7, model: "gpt-5", capabilities: { webSearch: true, dataAnalyst: true } }, messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "What are the key points in the document?" } ] } ] }) } ); const data = await response.json(); console.log(data); ``` ### Using Structured Output with Schema ```javascript theme={null} const response = await fetch( "https://api.langdock.com/agent/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ agent: { name: "Weather Agent", instructions: "You are a helpful weather agent", model: "gpt-5", capabilities: { webSearch: true } }, messages: [ { id: "msg_1", role: "user", parts: [ { type: "text", text: "What's the weather in Paris, Berlin and London today?" } ] } ], output: { type: "array", schema: { type: "object", properties: { weather: { type: "object", properties: { city: { type: "string" }, tempInCelsius: { type: "number" }, tempInFahrenheit: { type: "number" } }, required: ["city", "tempInCelsius", "tempInFahrenheit"] } } } } }) } ); const data = await response.json(); console.log(data.output); // Output: // [ // { "weather": { "city": "Paris", "tempInCelsius": 1, "tempInFahrenheit": 33 } }, // { "weather": { "city": "Berlin", "tempInCelsius": 1, "tempInFahrenheit": 35 } }, // { "weather": { "city": "London", "tempInCelsius": 7, "tempInFahrenheit": 45 } } // ] ``` ### Using with Next.js Server Actions ```typescript theme={null} // app/actions.ts 'use server'; import { generateId } from 'ai'; export async function chatWithAgent(message: string) { const response = await fetch( 'https://api.langdock.com/agent/v1/chat/completions', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.LANGDOCK_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: process.env.AGENT_ID, messages: [ { id: generateId(), role: 'user', parts: [ { type: 'text', text: message } ] } ] }) } ); const data = await response.json(); return data.messages[0].content; } ``` ## Rate Limits The rate limit for the Agents Completions endpoint is **500 RPM (requests per minute)** and **60,000 TPM (tokens per minute)**. Rate limits are defined at the workspace level - not at an API key level. Each model has its own rate limit. If you exceed your rate limit, you will receive a `429 Too Many Requests` response. Please note that the rate limits are subject to change. Refer to this documentation for the most up-to-date information. ## Error Handling ```javascript theme={null} try { const response = await fetch('https://api.langdock.com/agent/v1/chat/completions', options); if (!response.ok) { const error = await response.json(); throw new Error(error.message || 'Request failed'); } const data = await response.json(); // Process response } catch (error) { console.error('Error:', error.message); } ``` Common error status codes: * `400` - Invalid request parameters, malformed message format, agent not found, or agent not shared with API key * `401` - Invalid or missing API key * `429` - Rate limit exceeded * `500` - Server error Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices). ## OpenAPI ````yaml POST /agent/v1/chat/completions openapi: 3.0.0 info: title: Langdock API version: 3.0.0 servers: - url: https://api.langdock.com security: - bearerAuth: [] paths: /agent/v1/chat/completions: post: tags: - Agent summary: Creates a chat completion with an agent (Vercel AI SDK compatible) description: Creates a model response using Vercel AI SDK compatible UIMessage format parameters: [] requestBody: required: true content: application/json: examples: streamingEnabled: summary: Request with streaming enabled value: agentId: agent_123 messages: - id: msg_1 role: user parts: - type: text text: Hello, how can you help me? stream: true schema: type: object oneOf: - type: object required: - agentId - messages properties: agentId: type: string description: ID of an existing agent to use messages: type: array description: Array of UIMessage objects (Vercel AI SDK format) items: type: object required: - id - role - parts properties: id: type: string description: Unique message identifier role: type: string enum: - user - assistant - system - tool parts: type: array items: type: object required: - type properties: type: type: string enum: - text - file - tool-invocation - tool-result text: type: string description: Text content for text parts url: type: string description: File URL for file parts name: type: string description: File name mimeType: type: string description: MIME type of the file toolCallId: type: string description: Tool call identifier toolName: type: string description: Name of the tool args: type: object description: Tool arguments result: type: object description: Tool result stream: type: boolean default: false output: $ref: '#/components/schemas/StructuredOutputConfig' imageResponseFormat: type: string enum: - url - b64_json description: >- Response format for images generated by the agent. "url" returns a signed URL, "b64_json" returns base64-encoded image data. responses: '200': description: Successful chat completion content: application/json: schema: type: object description: UIMessage response (Vercel AI SDK format) required: - id - role - parts properties: id: type: string role: type: string enum: - assistant parts: type: array items: type: object output: description: Structured output if requested '400': description: Invalid request parameters '429': description: Rate limit exceeded '500': description: Internal server error components: schemas: StructuredOutputConfig: type: object description: >- Specification for structured output format. When type is object/array and no schema is provided, the response will be JSON but can have any structure. When the type is enum, you must provide an enum parameter with an array of strings as options. properties: type: type: string enum: - object - array - enum description: The type of structured output schema: type: object description: >- JSON Schema definition for the output (required for object/array types with specific structure). Search for "JSON to JSON Schema" in the web to find a tool to convert any JSON into the required JSON Schema format. enum: type: array items: type: string description: >- Array of allowed values (required for enum type). Values must be of type string. oneOf: - properties: type: enum: - enum enum: type: array items: type: string - properties: type: enum: - object - array schema: type: object - properties: type: enum: - object - array securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: API key as Bearer token. Format "Bearer YOUR_API_KEY" ````