---
title: "Creates a chat completion with an agent (Vercel AI SDK compatible)"
method: POST
path: "/agent/v1/chat/completions"
tags: ["Agent"]
---

# Creates a chat completion with an agent (Vercel AI SDK compatible)

`POST /agent/v1/chat/completions`

## Request

- Base URL: `https://api.langdock.com`
- URL: `https://api.langdock.com/agent/v1/chat/completions`
- Auth: HTTP bearer

Creates a model response using Vercel AI SDK compatible UIMessage format

## Request body

- object
  - `agentId` string, required: ID of an existing agent to use
  - `messages` object[], required: Array of UIMessage objects (Vercel AI SDK format)
    - `id` string, required: Unique message identifier
    - `role` 'user' | 'assistant' | 'system' | 'tool', required: Extra history messages with role system stay as user context. A last message that is not user is dropped.
    - `parts` object[], required
      - `type` 'text' | 'file' | 'tool-invocation' | 'tool-result', required
      - `text` string: Text content for text parts
      - `url` string: File URL for file parts
      - `name` string: File name
      - `mimeType` string: MIME type of the file
      - `toolCallId` string: Tool call identifier
      - `toolName` string: Name of the tool
      - `args` object: Tool arguments
      - `result` object: Tool result
  - `stream` boolean
  - `output` union: 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.
    - object
      - `type` 'enum': The type of structured output
      - `schema` object: 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` string[]: Array of allowed values (required for enum type). Values must be of type string.
    - object
      - `type` 'object' | 'array': The type of structured output
      - `schema` object: 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` string[]: Array of allowed values (required for enum type). Values must be of type string.
    - object
      - `type` 'object' | 'array': The type of structured output
      - `schema` object: 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` string[]: Array of allowed values (required for enum type). Values must be of type string.
  - `imageResponseFormat` 'url' | 'b64_json': Response format for images generated by the agent. "url" returns a signed URL, "b64_json" returns base64-encoded image data.

## Response `200`

Successful chat completion

- object: UIMessage response (Vercel AI SDK format)
  - `id` string, required
  - `role` 'assistant', required
  - `parts` object[], required
  - `output` unknown

## Other responses

- `400`: Invalid request parameters, or an attached integration file the API key cannot read. One unreadable file stops the call even when other files are readable, and for that error the message and `details.attachmentIds` list the attachment IDs.
- `429`: Rate limit exceeded, the integration rate-limited the access check for an attached integration file, or the workspace reached its monthly spending limit. For the access check, the message and `details.attachmentIds` list the attachment IDs.
- `500`: Internal server error
- `503`: Access check unavailable for an attached integration file. The message lists the attachment IDs, and the response has no `details`.

## Changes

- **2026-11-03** `c62bf90b4013`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/langdock/apis/langdock-api/changes/agent/v1/chat/completions/post.md)

---

[API](https://skmtc.dev/langdock/apis/langdock-api.md) - [All operations](https://skmtc.dev/langdock/apis/langdock-api/llms.txt) - [OpenAPI document](https://skmtc.dev/langdock/apis/langdock-api/revisions/c62bf90b4013?raw)