Agent Configuration
Purpose and Scope
Agent configuration in LlamaIndex is the process of assembling a workflow-compatible agent from four practical concerns: the model that reasons, the tools it can call, the memory that carries conversation state, and the instructions or message structure that frame its behavior. The public API index identifies the workflow agent family as the primary surface: AgentWorkflow, BaseWorkflowAgent, FunctionAgent, ReActAgent, and CodeActAgent, plus runtime payload types such as AgentInput, AgentStream, AgentOutput, ToolCall, and ToolCallResult. That tells readers to think of agents as workflow participants with typed inputs, streamed events, outputs, and tool-call records rather than as isolated helper functions.
Sources: docs/api_reference/api_reference/agent/index.md
The most important configuration decision is choosing the agent style that matches the model and task. A function-calling agent is appropriate when the selected LLM natively supports structured tool calls. A ReAct agent is useful when the application benefits from explicit reasoning-and-acting loops. A CodeAct agent is aimed at agents that write and execute code. All of these belong to the workflow-oriented API family, so they are intended to compose with workflow orchestration and multi-agent patterns instead of only serving one-off chat requests.
Sources: docs/api_reference/api_reference/agent/index.md
Relevant Source Files
docs/api_reference/api_reference/agent/index.md— Declares the official Agent Classes API page and names the workflow agent classes and runtime event/result types.llama-index-core/llama_index/core/base/llms/types.py— Defines the message roles and content-block primitives used when prompts, chat messages, multimodal inputs, and model-facing data are represented.llama-index-core/llama_index/core/memory/types.py— DefinesBaseMemoryandBaseChatStoreMemory, including synchronous and asynchronous chat-history operations for stateful agents.llama-index-core/llama_index/core/tools/types.py— DefinesToolMetadata,DefaultToolFnSchema,ToolOutput, and OpenAI-compatible tool serialization behavior used by tool-calling agents.
Core Primitives
The LLM layer supplies the vocabulary for instructions and user-visible messages. MessageRole includes system, developer, user, assistant, function, tool, chatbot, and model, giving agent applications a typed way to distinguish policy-setting messages from user turns, assistant responses, and tool/function exchanges. Content is modeled through content blocks that can be estimated, split, merged, and truncated by token count. This matters for agents because tool outputs, user requests, and chat history often need to fit inside a model context window while preserving the semantic role of each message.
Sources: llama-index-core/llama_index/core/base/llms/types.py
Tools are configured through metadata as much as through executable code. ToolMetadata carries a description, optional name, optional Pydantic function schema, and return_direct flag. If no schema is supplied, the default schema is a single string input field. When a schema is supplied, the tool contract is reduced to the JSON-schema fields expected by model tool-calling APIs: object type, properties, required fields, and definitions. Good agent configuration therefore requires concise descriptions, stable names, and schemas that accurately describe what the tool accepts.
Sources: llama-index-core/llama_index/core/tools/types.py
Memory supplies the state boundary for conversational agents. BaseMemory defines the core contract: create from defaults, get chat history, get all history, put messages, set messages, and reset. Each operation also has asynchronous variants that delegate work safely through async helpers. BaseChatStoreMemory adds a chat_store and chat_store_key, defaulting to SimpleChatStore and chat_history, so a single memory abstraction can support multi-tenant or keyed histories without changing the agent interface that consumes memory.
Sources: llama-index-core/llama_index/core/memory/types.py
System-to-Code Mapping
| Configuration concern | Public type or member | What it controls | Source |
|---|---|---|---|
| Workflow agent class | AgentWorkflow, BaseWorkflowAgent, FunctionAgent, ReActAgent, CodeActAgent | The agent runtime style and workflow compatibility boundary | docs/api_reference/api_reference/agent/index.md |
| Runtime events and results | AgentInput, AgentStream, AgentOutput, ToolCall, ToolCallResult | The typed data that moves through agent execution | docs/api_reference/api_reference/agent/index.md |
| Message roles | MessageRole | The role assigned to system, developer, user, assistant, tool, and function messages | llama-index-core/llama_index/core/base/llms/types.py |
| Tool schema | ToolMetadata, DefaultToolFnSchema | Tool names, descriptions, JSON schemas, and direct-return behavior | llama-index-core/llama_index/core/tools/types.py |
| Tool result | ToolOutput | Structured return blocks, raw inputs, raw outputs, and error state | llama-index-core/llama_index/core/tools/types.py |
| Conversation state | BaseMemory, BaseChatStoreMemory | Chat-history retrieval, mutation, reset, async access, and chat-store-backed persistence | llama-index-core/llama_index/core/memory/types.py |
Configuration Flow
A typical agent configuration starts by selecting the workflow class, then supplying an LLM and a set of tools. The official examples index presents Function Calling Agent, ReAct Agent, CodeAct Agent, and Multi-Agent Workflow as the main learning paths, which aligns with the API index naming. The LLM choice determines whether the agent should rely on native structured tool calls or a prompting pattern such as ReAct. The tool list then defines the boundary between model reasoning and application actions, such as search, retrieval, database access, or custom business functions.
Sources: docs/api_reference/api_reference/agent/index.md, llama-index-core/llama_index/core/tools/types.py
Instructions should be treated as model-facing messages rather than as arbitrary comments. The LLM type layer distinguishes system and developer roles from user and assistant roles, so durable policy, task framing, safety constraints, and style guidance should be placed where the chosen agent and model provider will preserve their intent. Because content blocks support token estimation, splitting, and truncation, applications that pass long tool results or multimodal content should plan how those blocks will be compressed or trimmed before they compete with instructions and chat history for context.
Sources: llama-index-core/llama_index/core/base/llms/types.py
Memory is added when the agent must behave statefully across turns. The BaseMemory contract makes chat history explicit: callers can retrieve the relevant history for a new input, append new messages, replace the whole history, or reset it. BaseChatStoreMemory is the configuration point when the state should be stored behind a chat-store abstraction and addressed by a key. That key defaults to chat_history, but the existence of the field is important for deployed or multi-session agents where one process may serve many conversations.
Sources: llama-index-core/llama_index/core/memory/types.py
API Components Reference
ToolMetadata.to_openai_tool(skip_length_check: bool = False) converts LlamaIndex tool metadata into an OpenAI-style function tool object. The method sanitizes tool names to characters accepted by OpenAI function names and rejects descriptions longer than 1024 characters unless length checking is skipped. ToolMetadata.to_openai_function() still exists but is marked deprecated in favor of to_openai_tool. These details matter when configuring agents against function-calling models, because the model sees the serialized schema and description, not the Python implementation.
Sources: llama-index-core/llama_index/core/tools/types.py
ToolOutput captures the result side of a tool call. It includes content blocks, the tool name, raw input, raw output, an is_error flag, and an optional private exception. That shape lets an agent runtime preserve both model-readable output and debugging or integration details. When a tool can fail, configuration should include descriptions and schemas that reduce invalid calls, while execution code should return error state in a form the agent can reason about or surface safely to the caller.
Sources: llama-index-core/llama_index/core/tools/types.py
BaseMemory exposes both synchronous and asynchronous methods: get and aget, get_all and aget_all, put and aput, put_messages and aput_messages, set and aset, plus reset and areset. The async methods are part of the public contract, so workflow agents can be used in asynchronous applications without forcing every memory backend to implement native async behavior. BaseChatStoreMemory overrides chat-history access to call the configured chat store directly.
Sources: llama-index-core/llama_index/core/memory/types.py
Implementation Guidance and Next Steps
Keep agent configuration small and explicit. Start with one workflow agent class, one LLM, and a narrow set of tools whose metadata is easy for the model to distinguish. Prefer strong Pydantic schemas over the default single-string input when the tool has structured parameters. Keep descriptions under the provider-facing limit and move lengthy operational guidance into the prompt or instruction messages. Add memory only when the task actually requires prior turns; otherwise, stateless runs are easier to test, replay, and evaluate.
Sources: llama-index-core/llama_index/core/tools/types.py, llama-index-core/llama_index/core/memory/types.py
After the first configuration works, expand along the runtime boundaries shown by the API index. Use AgentStream when the client needs incremental progress, inspect ToolCall and ToolCallResult when debugging tool behavior, and move from a single agent class to AgentWorkflow when orchestration becomes more important than a single reasoning loop. For adjacent documentation, read the Agents Overview for the conceptual model, Tools for tool authoring details, Workflows for orchestration, Sessions for persisted conversation state, and Streaming for client-facing event delivery.
Sources: docs/api_reference/api_reference/agent/index.md