Agents

An agent is a saved setup: a model, a system prompt, and the tools and files it can use. You build it once in the Agent Builder, then pick it whenever you start a chat. Agents work with any provider you have configured, not just OpenAI.

Create an agent

Uploading files for File Search or File Context only works once the agent has been created.

To chat with an agent, select it in the model selector, open it from the Agent Marketplace, or type @ in the chat box and pick it from the list. In the builder's agent selector, My agents narrows the list to agents you created.

Instructions from a saved prompt

With the instructions source set to Prompt, an agent's instructions can link to a saved prompt instead of inline text. The agent follows the prompt's production version or a pinned version, and the linked prompt can be native to LibreChat or synced from Langfuse. See Use a prompt as agent instructions.

Instructions, inline or linked, can use {{current_date}}, {{current_datetime}}, and {{iso_datetime}}. They are filled in once at the start of each turn and stay the same through tool calls, subagents, and approval pauses. The first two use your time zone; {{iso_datetime}} is UTC.

Model parameters

The model panel exposes the same parameters as a normal chat for that provider (temperature, max output tokens, and so on), plus Image Detail for vision input. Values saved here apply to every conversation with the agent.

Conversation starters

Under Conversation Starters you can add up to four prompts. They appear as buttons on the empty chat screen when someone starts a new chat with the agent, and clicking one sends it straight away. An agent's starters replace any starters defined on the model spec in use. They also appear in the agent's Marketplace details.

Version history

Every save that changes the agent adds an entry to Version History, which shows when each version was saved and which tools and capabilities it had. Restore replaces the current configuration with that version after a confirmation. Only users who can edit the agent see this.

Tools

Click Add next to the Tools heading in the builder (it reads No tools yet until you add one) to open the Tool Library. Search it, or filter by Native, Tools, MCP servers, or Actions. Made by you collects the MCP servers and Actions you created, and Favorites keeps starred items handy across agents (up to 100). The Create new… menu adds an MCP server or an Action without leaving the dialog, if your role is allowed to create them. What you see depends on what your admin has enabled and on your role's permissions; an item that still needs an API key shows Needs setup.

Run Code, File Search, and File Context hold files. While they still have files attached, removing them opens the file manager instead, and they stay on the agent until those files are removed.

Code Interpreter

Listed as Run Code. The agent writes and runs code in a sandbox, which is what you want for calculations, data analysis, and producing files such as charts or spreadsheets. Files you attach to this tool in the builder are available in the sandbox on every run. If none of a conversation's code files can be restored into the sandbox, the agent stops before calling the model and asks you to attach them again. See Code Interpreter.

Stateful code sessions

If your admin has enabled them, Stateful code sessions in the Run Code settings keep a sandbox workspace between runs, so files and installed packages carry over. Stateful environment sets who shares that workspace: User workspace (recommended) for all your stateful agents, Agent + user workspace for one per agent, or Conversation workspace for one per chat. New agents start from the Default stateful workspace in Settings > Data & Privacy > Code execution. Where the admin has set up several backends, Execution environment picks which one runs the code, which can include a worker you pair on your own machine.

The workspace can be reset at any time, so do not treat it as storage. In managed environments, save outputs you need under /mnt/data. Files the agent writes with its file tools are listed per message under Workspace changes, where you can download them. With an attached environment, the composer offers Ask before changes, Accept edits, or Full access as the approval mode for that chat, within limits your admin sets.

This feature is highly experimental. See stateful code sessions for details.

Web Search

The agent searches the web and cites its sources. It needs a search provider configured by your admin, or your own key if the admin set it up that way. See Web Search.

File Search

Turns the files you attach into a searchable knowledge base. The agent pulls the most relevant passages when it needs them, so it copes with large document sets. It is a poor fit for structured data like CSV or Excel, where Run Code does better. Requires the RAG API.

File Context

Files added under File Context have their text extracted once, at upload, and that text goes into the agent's context on every message. Use it for a few key documents the agent should always have in front of it. Extraction works the same way as Upload as Text: plain text parsing by default, better results on scans and images if OCR is configured.

Because the text rides along with every message, large files here cost tokens on every turn. Anyone who can chat with the agent can also coax that text out of it.

Artifacts

Lets the agent render React, HTML, SVG, Markdown, and Mermaid in a side panel instead of as code blocks. The Mode setting picks the built-in instructions: Normal, shadcn/ui (adds instructions for the shadcn/ui component library), or Custom, which injects nothing, so your own instructions must teach the artifact syntax. See Artifacts for that syntax.

Model Context Protocol (MCP)

MCP servers your admin configured, or that you added yourself, appear under MCP servers. Adding a server attaches all of its tools; expand it under Tools in this server to pick only the ones the agent needs. See MCP.

Some servers can only list their tools during a chat, because they depend on values from the request. For those, the builder offers one selection for all the server's tools instead of per-tool switches. If an agent's selected MCP tools all fail to load when a run starts, the run stops and tells you to reconnect or sign in to the server rather than carrying on without them.

Each MCP tool has a Tool Options menu with a few per-tool switches:

• Defer: see Deferred tools. Defer all tools does it for the whole server.
• Programmatic: see Programmatic tool calling.
• Background: see Background tool calls.
• Intent label: the agent writes a one-line description of each call, shown live as the call's status instead of a generic label. It adds a few tokens per request. Native tools get intent labels automatically. This does not apply to programmatic tools.

Background and Intent label only appear if your admin has enabled them.

Deferred tools

An agent with several MCP servers can easily carry dozens of tool definitions, and sending all of them on every request eats context and makes the model worse at picking the right one. A deferred tool is left out of the initial request. The agent gets a tool search tool instead, finds deferred tools by name or description when it needs them, and can use a found tool for the rest of the conversation.

Programmatic tool calling

With Programmatic turned on for an MCP tool (or a whole server), the model does not call that tool directly. It writes code in the Code Interpreter sandbox that calls the tool as a function, so it can loop, paginate, retry, and filter results before answering. This helps with jobs like "check these 40 tickets and summarize the open ones", which would otherwise take 40 separate tool calls through the model.

The Programmatic switches stay disabled until Run Code is on, and removing Run Code clears them. The sandbox can only call tools that are registered on the agent. While it runs, expand the code card to watch a live trace of each inner tool call; the trace is not kept after you reload the page. This is off by default; your admin has to enable it.

Background tool calls

A background-capable tool returns a task reference right away, so the agent can keep working while it runs. When the task finishes, the result is delivered in a follow-up turn automatically (shown as a collapsible task card), or the agent can check on it with its task tool. Background output and files appear on the original tool call. Which tools may run in the background:

• Run Code: code and shell commands are eligible by default; turn off Background execution in its settings to opt out.
• MCP tools: mark a tool or a whole server Background.
• Other tools and Actions: turn on Background execution. Actions that use OAuth do not offer it.

These switches allow background execution; the model still decides per call. Background work runs in the server process that started it and is lost if that process dies. Your admin has to enable the feature.

Actions

Actions turn an OpenAPI spec into tools. Choose Create new… then Actions, paste the schema, and set up Authentication if the API needs it. Each operation in the spec becomes a tool the agent can call.

If you are using an OpenAI model, add x-strict: true to an operation in the spec and LibreChat will request strict function calling for it. Strict mode accepts only a subset of JSON Schema; see OpenAI's structured outputs guide.

Actions can only reach domains your admin allows, and private network addresses are blocked unless explicitly allowed.

Skills

The Skills section in the builder controls which Skills the agent can use: Off, All (every skill you have active), or Selected (only the ones you add).

Memory

Memory lets the agent save, update, and delete memories about you when you ask it to remember or forget something. It needs memory to be set up on the instance and allowed for your role. By default the agent shares your personal memories with your other chats; turn on Keep memories separate for this agent to give it its own memories that it alone reads and writes. See Memory.

Ask User and tool approval

Ask User lets the agent pause mid-run to ask you something and wait. One pause can hold up to four questions, shown one at a time with Back and Next; each takes a free-form answer or one of the agent's choices. Skip declines all of them. The run resumes as soon as you submit, and your answers are kept even if you stop while it restarts.

Your admin can also require approval before certain tools run. The run pauses, you review the call in a panel above the message box (approve, reject, or for some tools edit the arguments), and it continues. If the admin has enabled per-agent approval modes, each tool on the agent gets a Tool approval mode: Use inherited policy, Always ask, Always approve, Ask once per chat, or Ask once, then always approve. Admin rules still apply on top, and Reset my remembered approvals clears what you have approved before.

Other tools

The Tools category holds the built-in integrations your admin has enabled, such as image generation, Wolfram, Google Search, and Azure AI Search. Each one is set up separately; see Tools.

Working with other agents

Subagents let the agent hand a focused subtask to a fresh copy of itself, or to another agent, in a separate context window. Only the result comes back, so long tool output stays out of the main conversation. See Subagents.

Handoffs

Handoffs give the agent a transfer tool for each agent you list, so it can pass the conversation to a specialist when the topic calls for it. For each handoff you can add a description (when to transfer) and passthrough content (what the agent should generate and pass along), and rename the parameter that content is passed in (instructions by default). An agent can have up to 10 handoffs. Handoffs are always available; they do not depend on an admin setting.

Agent chain

Agent chains are deprecated. Existing chains still run, and the builder shows them under Advanced Settings with a Remove chain button, but you cannot create new ones. Use subagents or handoffs instead.

Max agent steps

Advanced Settings has a Max Agent Steps field that caps how many steps the agent can take before it has to give a final answer. A step is one model request or one round of tool calls, so a single tool call usually costs three steps: the request, the tool round, and the follow-up request.

Leave it empty to use the server default, which is 50 unless your admin changed it. Your admin can also set a ceiling that the field cannot exceed.

When a turn runs out of steps, you keep what the agent did so far, and the message offers Keep going (a new turn with a fresh budget) or Answer now (the agent answers from the work already done, without more tools). If this happens often on long tool chains, raise the limit.

Following a long run

Tool cards show Preparing while a call waits (for example on approval) and then Calling until the result comes back. Shell output is shown terminal-style and collapsed to the last 15 lines; Show more expands it, and a command that failed shows its exit code, signal, or timeout.

Activity groups

If your admin has turned them on, each stretch of reasoning and tool calls collapses under a generated one-line header, so a run with 30 tool calls reads as a handful of lines. Expand a header to see the calls inside it. A second level can wrap several of those groups into a phase with its own summary, giving long runs an outline; once two groups have finished, they fold together right away, with the latest header standing in until the summary arrives. The final answer always stays outside the fold, and files produced inside a phase are shown in a row under it rather than hidden. With Smooth Streaming on, the fold is animated, unless your device asks for reduced motion.

Live reasoning labels are a related option: instead of a generic Thinking heading, the reasoning block shows a short, updating summary of what the model is working on.

Headers, phase summaries, and reasoning labels each cost extra model calls, which are recorded like any other usage. Admins configure them in agent activity groups and live reasoning labels.

Steering and queued messages

While an agent is answering, you can still send messages:

• Steer slips the message into the current run at the next safe point, so the agent can adjust before it finishes.
• Interrupt cancels the tool calls and reasoning in progress, keeps what is done, and continues with your message. Effects that already happened outside LibreChat cannot be undone. Some runs, for example ones using a provider's built-in search, cannot be interrupted, and the message waits as a steer instead.
• Queue holds the message and sends it as a normal turn after the answer completes.

While generating, Enter will under Settings > Chat picks the default, and the send button menu overrides it per message; Alt + Enter interrupts. Queued messages are listed above the composer, where you can edit, remove, reorder, Send now, or Interrupt now. Files and quoted excerpts go along with the message; skills you picked with $ wait for the next full turn. Queued messages in a saved agent chat are stored on the server and survive a closed browser.

A chat holds up to 100 queued messages (16,000 characters and 10 files each), and a run takes up to 10 pending steers. See Composer for the receipts and controls in detail.

Files in a chat

When you chat with an agent, the attach menu offers:

• Upload Image: sent to the model for vision.
• Upload as Text: the full text goes into this conversation only. See Upload as Text.
• Upload for File Search: indexed for retrieval, like the agent's own File Search files but scoped to this chat.
• Upload to Code Environment: copied into the sandbox for Run Code. Best for CSV, Excel, and JSON.

Options only appear when the matching capability is enabled.

Sharing and permissions

Agents are private to their author until shared. Click Share in the builder footer to give users, groups, or roles access, each with one of three roles:

Share with everyone makes the agent available to every user on the instance; it needs the public sharing permission. The author and admins always keep full control.

A viewer cannot see the instructions or files in the builder, but the model can still repeat them in a conversation if asked. Do not put anything in an agent that its viewers should never see.

Separately, the globe button (Remote Access) controls who can call the agent through the Agents API.

Agent cards show the support contact set in the builder. Without one, they may show the owner's name, but never the owner's email unless it was entered as the contact.

See Access Control for how users, groups, and roles combine.

Administrator controls

Whether a role can use, create, share, or publicly share agents is set per role in the Admin Panel. Admins also get an Admin Settings button at the bottom of the Agent Builder with the same switches, per role. On a single-tenant instance the first account registered is an admin; to add more, see Promote another admin.

Agent Marketplace

Agent Marketplace in the sidebar lists the agents available to you, if your role may use it. Search by name or description, filter by category (Top Picks, All, or a specific one), and change the order with Sort by: Newest first, Oldest first, Popular, or By creator name. My agents shows only yours. The search, sort, and filter are kept in the URL, so you can bookmark or share a view.

Click a card for details and the actions Pin or Unpin, Copy Link (a link that opens a new chat with the agent), and Start Chat. Clicking one of the agent's conversation starters there opens a new chat with the prompt in the message box, unsent, so you can edit it first.

Agents API

Agents can also be called from scripts and other apps through an OpenAI-compatible API, managed by trusted services, and triggered by events from other systems. See Agents API. Scheduled Chats start agent runs on a timer, and Agent Plugins let an operator ship skills and MCP servers to agents as one package.

Setup

Agents are on by default. Admins choose which capabilities are offered, the step limits, and the allowed providers in the agents endpoint configuration, and which domains Actions may reach in Actions configuration. Instances upgraded from before v0.8.0-rc3 need the permissions migration.