Agent API
Purpose and Scope
This page is the focused API entry point for LlamaIndex agent classes and the type surfaces that agent implementations commonly share. In LlamaIndex, an agent is not just a prompt wrapper around a language model. It is an orchestration component that can receive user input, decide when to call tools, represent intermediate events, and return structured outputs. The official API reference exposes the workflow-oriented agent family through the agent index, while the supporting core modules define lower-level contracts for reasoning traces and tool conversion. Use this page when you need to connect the public agent class names to the source types that shape tool calls, ReAct reasoning, and agent-facing responses.
Sources: docs/api_reference/api_reference/agent/index.md, llama-index-core/llama_index/core/agent/react/types.py, llama-index-core/llama_index/core/tools/types.py
The most important distinction for readers is between the high-level agent classes and the data structures that make agent execution observable. The API index names workflow agents such as AgentWorkflow, BaseWorkflowAgent, FunctionAgent, ReActAgent, and CodeActAgent, plus event and result types such as AgentInput, AgentStream, AgentOutput, ToolCall, and ToolCallResult. The ReAct type module then shows how a reasoning trace is expressed as action, observation, or final response steps. The tool type module shows how tools describe their schema, how they are converted for model providers, and how results are packaged back into agent execution.
Relevant Source Files
docs/api_reference/api_reference/agent/index.md- the generated documentation entry point for agent classes; it lists the public members exported fromllama_index.core.agent.workflowfor API documentation.llama-index-core/llama_index/core/agent/react/types.py- defines base and concrete ReAct reasoning step models used to represent thoughts, actions, observations, and final answers.llama-index-core/llama_index/core/tools/types.py- defines shared tool metadata, default function schemas, provider conversion helpers, and tool output packaging used by agents and tool-calling workflows.
Public Agent Reference Surface
The generated agent API index is intentionally narrow: it points documentation at llama_index.core.agent.workflow and enumerates the workflow agent members that should appear in the public reference. The named classes cover both orchestration and concrete agent styles. AgentWorkflow is the workflow-level coordinator, BaseWorkflowAgent is the shared base for workflow-compatible agents, and concrete classes such as FunctionAgent, ReActAgent, and CodeActAgent describe agent strategies. The same index also lists message-like and event-like types: AgentInput, AgentStream, AgentOutput, ToolCall, and ToolCallResult. That grouping is useful because it tells readers that agent APIs are expected to model both the runner and the runtime data moving through it.
Sources: docs/api_reference/api_reference/agent/index.md
| API member | Role in the agent surface |
|---|---|
AgentWorkflow | Workflow-level agent orchestration entry point listed in the generated agent API reference. |
BaseWorkflowAgent | Common workflow-compatible agent base named by the API index. |
FunctionAgent | Concrete function-calling agent class named by the API index. |
ReActAgent | Concrete reasoning-and-acting agent class named by the API index. |
CodeActAgent | Concrete code-action oriented agent class named by the API index. |
AgentInput | Agent input type named as part of the workflow agent surface. |
AgentStream | Streaming event type named as part of the workflow agent surface. |
AgentOutput | Agent output type named as part of the workflow agent surface. |
ToolCall | Tool invocation type named as part of the workflow agent surface. |
ToolCallResult | Tool result type named as part of the workflow agent surface. |
For application developers, this means the agent API should be approached in layers. Start with the concrete class that matches the reasoning behavior you need, then inspect the shared input, stream, and output types if you are integrating the agent into a workflow runner, service endpoint, or user interface. If your agent needs callable capabilities, read the tool contracts before designing the agent prompt. Tool metadata determines what the model sees as a callable function, while tool output determines what the rest of the agent loop receives after execution. The API index gives the official names, and the core type modules explain the data expectations behind those names.
ReAct Reasoning Step Types
The ReAct support module defines a small hierarchy centered on BaseReasoningStep. The base class inherits from LlamaIndex's Pydantic bridge model and requires two behaviors: get_content() must return a displayable textual representation, and is_done must report whether the step terminates reasoning. This is a compact but important contract. Agents and debugging tools can treat multiple reasoning step subclasses uniformly, asking each step for content and completion state without knowing whether it represents a planned tool action, a tool observation, or a final natural-language answer.
Sources: llama-index-core/llama_index/core/agent/react/types.py
ActionReasoningStep represents the point where a ReAct agent has decided to do something. Its fields are thought, action, and action_input. The content string is formatted as a thought, an action name, and an action input payload. Its is_done property always returns false, which reflects the ReAct loop: choosing an action is not the end of the agent run, because the tool still needs to be executed and its observation must be fed back into the next step. When you are logging or rendering ReAct traces, this is the structure that separates model reasoning from the concrete tool input it selected.
ObservationReasoningStep captures what happened after an action. It stores an observation string and a return_direct flag. Its content is formatted as an observation, and its completion state is exactly the value of return_direct. That design is significant for tool behavior. A tool can return information that should merely inform the next reasoning step, or it can produce an answer that should be returned directly to the caller. The type makes that control flow explicit, so agent loops can terminate early when the observation is already the desired response.
ResponseReasoningStep represents the final answer. It stores a thought, a response, and an is_streaming flag. Its is_done property always returns true, which marks it as the terminal ReAct step. The content formatter also treats streaming specially: when streaming is active, the response text is described as the beginning of an answer rather than a complete answer. This is a useful signal for user interfaces and logs, because it lets an agent trace show partial generation without pretending the final response has already been fully materialized.
Tool Type Contracts for Agents
Tools are a central part of the agent API because workflow agents use them to connect model decisions with application behavior. The tool type module defines DefaultToolFnSchema, a Pydantic model with a single input string, and ToolMetadata, a dataclass that describes a callable tool. ToolMetadata contains a human-readable description, an optional name, an optional fn_schema, and a return_direct flag. These fields are not cosmetic. They shape the JSON schema supplied to tool-capable model providers and influence whether tool results should continue the agent loop or be returned immediately.
Sources: llama-index-core/llama_index/core/tools/types.py
The schema behavior is explicit. If fn_schema is absent, get_parameters_dict() builds a default object schema with one required string property named input. If a Pydantic schema is provided, the method asks the model for JSON schema and then filters it down to the keys relevant for provider tool definitions, including type, properties, required fields, definitions, and $defs. This lets a simple text tool and a structured multi-argument tool share the same metadata path. It also means developers should keep tool schemas precise, because the generated parameter dictionary is what downstream model-facing conversion methods use.
The conversion helpers encode provider-facing constraints. fn_schema_str serializes the parameter schema as JSON and raises an error if fn_schema is missing. get_name() raises an error if the metadata has no name. _sanitize_name() replaces characters outside the OpenAI function-name character set with underscores, which protects generated tool definitions from invalid names such as generic Pydantic type names containing brackets. to_openai_function() remains present but is deprecated in favor of to_openai_tool(). The newer method returns an object with type function and a nested function definition, and it enforces a maximum description length of 1024 characters unless the caller opts out.
ToolOutput packages the result of a tool call for the rest of the agent system. Its fields include content blocks, the tool name, raw input, raw output, and an is_error flag. It also keeps an optional private exception. This shape is helpful because agents need more than a printable string after calling a tool. They may need the original structured output for downstream logic, the raw input for tracing, an error marker for recovery, and content blocks compatible with language-model message formats. When implementing custom tools, preserve this distinction between user-visible content and raw execution data.
Execution Flow and Edge Cases
A typical agent run combines the surfaces above in a predictable order. The application sends input to one of the public workflow agent classes. The agent decides whether a tool should be called, using tool metadata to expose callable names, descriptions, and parameter schemas to the model. If the strategy is ReAct-style, an action reasoning step records the model thought and selected action. After tool execution, an observation reasoning step records what the tool returned and whether the result should be returned directly. Finally, a response reasoning step marks the run complete, with streaming-aware content if the answer is being emitted incrementally.
Sources: docs/api_reference/api_reference/agent/index.md, llama-index-core/llama_index/core/agent/react/types.py, llama-index-core/llama_index/core/tools/types.py
Several implementation details matter when moving from examples to production. Tool names should be set before provider conversion, because name access can fail when missing. Tool descriptions should be concise enough for provider limits, or conversion to an OpenAI tool can raise a validation error. If a tool has a structured schema, make sure the schema fields reflect what the function actually accepts, because the agent will expose that schema to the model as the callable contract. If return_direct is used, test the full reasoning path carefully: direct returns are convenient for search or lookup tools, but they intentionally bypass additional reasoning steps.
Next Steps
Use this page as the bridge between agent concepts and the generated API reference. If you are choosing an agent implementation, inspect the AgentWorkflow, FunctionAgent, ReActAgent, and CodeActAgent entries in the official agent reference. If you are building tools for those agents, review the tool metadata and output behavior first, because tool schemas and direct-return settings can change the runtime loop. If you are debugging an agent, inspect ReAct reasoning step content and completion state to understand whether the run is still planning, waiting on an observation, or already producing a final answer.