Agents - LibreChat

Overview

The Agents API allows you to create, manage, and interact with AI agents. Agents are AI assistants with custom instructions, tools, and capabilities. All agent endpoints are prefixed with /api/agents.

List Agents

Retrieve accessible agents:

GET /api/agents
Authorization: Bearer <token>

Query Parameters

limit

number

Maximum number of agents to return

after

string

Cursor for pagination

Response

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Code Assistant",
      "description": "Helps with code review and debugging",
      "author": "user123",
      "model": "gpt-4",
      "provider": "openai",
      "tools": ["code_interpreter"],
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "has_more": false
}

Get Agent

Retrieve a specific agent by ID:

GET /api/agents/:agent_id
Authorization: Bearer <token>

Path Parameters

agent_id

string

required

Agent ID

Response

string

Unique agent identifier

name

string

Agent name

description

string

Agent description

instructions

string

System instructions for the agent

model

string

Model identifier (e.g., gpt-4, claude-3-opus)

provider

string

Provider identifier (e.g., openai, anthropic)

tools

string[]

Array of enabled tool identifiers

tool_resources

object

Tool-specific resources (e.g., file_ids for code_interpreter)

author

string

User ID of the agent creator

avatar

object

Avatar configuration

{
  "id": "agent_abc123",
  "name": "Code Assistant",
  "description": "Helps with code review and debugging",
  "instructions": "You are an expert code reviewer...",
  "model": "gpt-4",
  "provider": "openai",
  "tools": ["code_interpreter", "web_search"],
  "tool_resources": {
    "code_interpreter": {
      "file_ids": ["file_xyz"]
    }
  },
  "author": "user123",
  "avatar": {
    "source": "custom",
    "filepath": "/avatars/agent_abc123.png"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-16T14:00:00Z"
}

Create Agent

Create a new AI agent:

POST /api/agents
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Research Assistant",
  "description": "Helps with research and fact-checking",
  "instructions": "You are a thorough research assistant...",
  "model": "gpt-4",
  "provider": "openai",
  "tools": ["web_search", "calculator"]
}

Request Body

name

string

required

Agent name (max 256 characters)

description

string

Brief description of the agent’s purpose

instructions

string

required

System instructions that define the agent’s behavior

model

string

required

Model to use (e.g., gpt-4, claude-3-opus)

provider

string

required

AI provider (e.g., openai, anthropic, google)

tools

string[]

Array of tool identifiers to enable

tool_resources

object

Tool-specific resources and configurations

temperature

number

Sampling temperature (0-2)

top_p

number

Nucleus sampling parameter (0-1)

Response

Returns the created agent object with HTTP status 201.

Update Agent

Update an existing agent:

PATCH /api/agents/:agent_id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Agent Name",
  "instructions": "Updated instructions...",
  "tools": ["web_search", "code_interpreter", "calculator"]
}

Path Parameters

agent_id

string

required

Agent ID to update

Request Body

All fields from Create Agent are optional for updates. Only include fields you want to change.

Response

Returns the updated agent object.

Delete Agent

Delete an agent:

DELETE /api/agents/:agent_id
Authorization: Bearer <token>

Path Parameters

agent_id

string

required

Agent ID to delete

Response

{
  "id": "agent_abc123",
  "deleted": true
}

Revert Agent Version

Revert an agent to a previous version:

POST /api/agents/:agent_id/revert
Authorization: Bearer <token>
Content-Type: application/json

{
  "version": 2
}

Path Parameters

agent_id

string

required

Agent ID

Request Body

version

number

required

Version number to revert to

Chat with Agent

Send a message to an agent and get a streaming response:

POST /api/agents/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversationId": "conv_abc",
  "agentId": "agent_123",
  "message": "Can you help me debug this code?",
  "attachments": []
}

Request Body

conversationId

string

required

Conversation ID (use UUID or new for new conversation)

agentId

string

required

ID of the agent to chat with

message

string

required

User message text

parentMessageId

string

ID of the parent message for threading

attachments

TAttachment[]

File attachments

Response

Returns a stream ID for Server-Sent Events (SSE) streaming:

{
  "streamId": "conv_abc",
  "conversationId": "conv_abc",
  "userMessage": {
    "messageId": "msg_user_123",
    "text": "Can you help me debug this code?"
  },
  "responseMessageId": "msg_ai_124"
}

Stream Agent Response

Subscribe to an agent’s streaming response:

GET /api/agents/chat/stream/:streamId?resume=true
Authorization: Bearer <token>

Path Parameters

streamId

string

required

Stream ID (usually equals conversationId)

Query Parameters

resume

boolean

Set to true for reconnection (sends sync event with resume state)

Response

Server-Sent Events (SSE) stream with the following event types:

Message Event

event: message
data: {"type":"content","text":"Hello! "}

event: message
data: {"type":"content","text":"I can help "}

event: message
data: {"type":"content","text":"you debug."}

event: message  
data: {"type":"done","messageId":"msg_ai_124"}

Sync Event (on reconnection)

event: message
data: {
  "sync": true,
  "resumeState": {
    "runSteps": [...],
    "aggregatedContent": [...]
  }
}

Error Event

event: error
data: {"error":"Generation failed"}

Abort Generation

Abort an ongoing agent response:

POST /api/agents/chat/abort
Authorization: Bearer <token>
Content-Type: application/json

{
  "streamId": "conv_abc",
  "conversationId": "conv_abc"
}

Request Body

streamId

string

Stream ID to abort

conversationId

string

Conversation ID

abortKey

string

Abort key (alternative identifier)

Response

{
  "success": true,
  "aborted": "conv_abc"
}

The partial response is automatically saved before returning.

Get Active Jobs

Get all active generation jobs for the current user:

GET /api/agents/chat/active
Authorization: Bearer <token>

Response

{
  "activeJobIds": ["conv_abc", "conv_xyz"]
}

Check Generation Status

Check if there’s an active generation for a conversation:

GET /api/agents/chat/status/:conversationId
Authorization: Bearer <token>

Path Parameters

conversationId

string

required

Conversation ID

Response

active

boolean

Whether generation is currently active

streamId

string

Stream ID if active

status

string

Job status: running, completed, or failed

aggregatedContent

array

Content generated so far

resumeState

object

Complete resume state for reconnection

{
  "active": true,
  "streamId": "conv_abc",
  "status": "running",
  "aggregatedContent": [
    {
      "type": "text",
      "text": "Partial response so far..."
    }
  ],
  "createdAt": "2024-01-15T10:00:00Z",
  "resumeState": {
    "runSteps": [],
    "aggregatedContent": []
  }
}

OpenAI-Compatible API

LibreChat provides an OpenAI-compatible API for agents:

Chat Completions

POST /api/agents/v1/chat/completions
Authorization: Bearer <api-key>
Content-Type: application/json

{
  "model": "agent_abc123",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": true
}

See the OpenAI Chat Completions documentation for full API details.

Available Tools

Agents can use the following tools:

code_interpreter - Execute Python code
web_search - Search the web
calculator - Perform calculations
file_search - Search uploaded documents
dalle - Generate images
Custom MCP (Model Context Protocol) tools

Permissions

Agent access is controlled by permissions:

VIEW: Can view agent details
USE: Can chat with agent
EDIT: Can modify agent configuration
DELETE: Can delete agent
SHARE: Can share agent with others

Only the agent author and users with appropriate permissions can access agents.

Error Responses

Agent Not Found

{
  "error": "Agent not found"
}

HTTP Status: 404

Insufficient Permissions

{
  "error": "Forbidden",
  "message": "Insufficient permissions to access this agent"
}

HTTP Status: 403

Job Not Found

{
  "error": "Job not found",
  "streamId": "conv_abc"
}

HTTP Status: 404

Overview

Endpoints

Integration

​Overview

​List Agents

​Query Parameters

​Response

​Get Agent

​Path Parameters

​Response

​Create Agent

​Request Body

​Response

​Update Agent

​Path Parameters

​Request Body

​Response

​Delete Agent

​Path Parameters

​Response

​Revert Agent Version

​Path Parameters

​Request Body

​Chat with Agent

​Request Body

​Response

​Stream Agent Response

​Path Parameters

​Query Parameters

​Response

​Message Event

​Sync Event (on reconnection)

​Error Event

​Abort Generation

​Request Body

​Response

​Get Active Jobs

​Response

​Check Generation Status

​Path Parameters

​Response

​OpenAI-Compatible API

​Chat Completions

​Available Tools

​Permissions

​Error Responses

​Agent Not Found

​Insufficient Permissions

​Job Not Found

Build docs developers (and LLMs) love

Overview

List Agents

Query Parameters

Response

Get Agent

Path Parameters

Response

Create Agent

Request Body

Response

Update Agent

Path Parameters

Request Body

Response

Delete Agent

Path Parameters

Response

Revert Agent Version

Path Parameters

Request Body

Chat with Agent

Request Body

Response

Stream Agent Response

Path Parameters

Query Parameters

Response

Message Event

Sync Event (on reconnection)

Error Event

Abort Generation

Request Body

Response

Get Active Jobs

Response

Check Generation Status

Path Parameters

Response

OpenAI-Compatible API

Chat Completions

Available Tools

Permissions

Error Responses

Agent Not Found

Insufficient Permissions

Job Not Found