Registry /
llm-agents / llama-index-agent-openai
Install & Compatibility
Where this runs
tested against v0.4.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 6.376s · 246.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 19.8s · import 5.836s · 242MB
257MB installed
● package 257MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIAgent
✓ from llama_index.agent.openai import OpenAIAgent
✗ from llama_index.agent.openai_agent import OpenAIAgent
The modular LlamaIndex (v0.10+) moved integrations to dedicated packages, standardizing the import path to `llama_index.agent.openai`.
OpenAI LLM
✓ from llama_index.llms.openai import OpenAI
✗ from llama_index.llms import OpenAI
OpenAI LLM is now found within the `llama-index-llms-openai` package, not directly from `llama_index.llms`.
This quickstart demonstrates how to initialize an `OpenAIAgent` with a custom `FunctionTool` and use it to perform calculations through conversational prompts. Ensure your `OPENAI_API_KEY` environment variable is set for successful authentication with OpenAI.
import os
from llama_index.agent.openai import OpenAIAgent
from llama_index.llms.openai import OpenAI
from llama_index.core.tools import FunctionTool
def multiply(a: int, b: int) -> int:
"""Multiply two integers and return the result integer"""
return a * b
# Define a tool from a function
multiply_tool = FunctionTool.from_defaults(fn=multiply)
# Initialize LLM with API key (ensure OPENAI_API_KEY is set in environment)
llm = OpenAI(
model="gpt-3.5-turbo",
api_key=os.environ.get('OPENAI_API_KEY', '') # Use os.environ.get for security
)
# Initialize OpenAI agent with tools
agent = OpenAIAgent.from_tools(
tools=[multiply_tool],
llm=llm,
verbose=True,
)
# Chat with the agent
response = agent.chat("What is 2 * 2?")
print(f"Agent Response: {response}")
response_complex = agent.chat("What is 10 times 5 plus 3?")
print(f"Agent Response (complex): {response_complex}")
Debug
Known issues
breakingLlamaIndex Modularization (v0.10+): `llama-index-agent-openai` is designed exclusively for the modular LlamaIndex (v0.10 and later). It explicitly requires `llama-index>=0.10.12`. Attempts to use it with older, monolithic LlamaIndex versions (e.g., v0.9.x) will result in import errors or runtime failures due to incompatible API structures.fixUpgrade your core `llama-index` installation to version `0.10.12` or newer using `pip install --upgrade llama-index llama-index-agent-openai`.
affects: <0.10.12 of llama-index
gotcha`openai` Python package version: This integration requires `openai>=1.1.0`. Using older `openai` versions (e.g., `0.x.x`) will cause `APIError` or `TypeError` due to significant changes in `openai`'s API, especially regarding client initialization and method calls (e.g., `openai.Completion` vs `client.chat.completions.create`).fixEnsure your `openai` package is `1.1.0` or newer: `pip install --upgrade openai`.
affects: <1.1.0 of openai
gotcha`OpenAIAgent` initialization with tools: The recommended and most robust way to initialize `OpenAIAgent` is using `OpenAIAgent.from_tools()`. Directly passing a `tools` argument to the constructor, or using older initialization patterns, might behave differently or be deprecated in future versions, potentially leading to incorrect tool invocation or agent behavior.fixAlways use `OpenAIAgent.from_tools(...)` for initializing agents with a list of tools.
affects: All (best practice)
gotchaOpenAI API Key Configuration: The OpenAI API key (traditionally `OPENAI_API_KEY`) must be correctly configured. If it's not set as an environment variable, it must be explicitly passed to the `OpenAI` LLM instance during initialization. Forgetting this will result in `AuthenticationError` from the OpenAI API.fixSet the `OPENAI_API_KEY` environment variable (e.g., `export OPENAI_API_KEY='sk-...'`) or pass it directly: `llm = OpenAI(api_key='sk-...')`.
affects: All (configuration)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_index.llms.openai'
This error occurs because the `llama-index-llms-openai` package, which provides the OpenAI LLM integration, is an optional dependency and needs to be installed separately from the core LlamaIndex library.
fixInstall the required package: `pip install llama-index-llms-openai`
ValueError: Tool description exceeds maximum length of 1024 characters. Please shorten your description or move it to the prompt.
OpenAI's function calling API has a character limit for tool descriptions. When defining `FunctionTool`s for `OpenAIAgent`, if the combined description length of all tools exceeds this limit, this error is raised.
fixShorten the `description` attribute of your `FunctionTool` instances, or for more complex scenarios, consider moving detailed descriptions into the LLM's system prompt or using a `QueryPlanTool` with descriptions moved to the prompt.
ValueError: LLM must be a FunctionCallingLLM
This error arises when an agent component (like `FunctionCallingAgentWorker` or `AgentWorkflow`) that relies on OpenAI's function calling capabilities is initialized with an LLM that either does not support function calling or is not correctly identified by LlamaIndex as a function-calling model.
fixEnsure you are using an OpenAI model that supports function calling (e.g., 'gpt-3.5-turbo' or 'gpt-4') and that your LLM instance is configured correctly, for example: `llm = OpenAI(model="gpt-4")`.
AttributeError: 'OpenAI' object has no attribute 'chat'
This error typically indicates a version mismatch between the installed `openai` Python client library and the LlamaIndex library's expectations, or incorrect usage of the `openai` client directly when LlamaIndex expects its own `LLM` abstraction.
fixEnsure you have compatible versions of `openai` and `llama-index` installed. If you are interacting with LlamaIndex agents, pass the `llama_index.llms.openai.OpenAI` LLM instance directly to the agent rather than a raw `openai` client object. If using the OpenAI client directly, ensure you are calling the correct methods (e.g., `client.chat.completions.create` instead of `client.chat`).
NotFoundError: Error code: 404 - {'error': {'message': 'Unrecognized request argument supplied: tools', 'type': 'invalid_request_error', 'param': None, 'code': None}}
This error often occurs when making an OpenAI API call (especially with Azure OpenAI) with a model version that does not support the `tools` argument or if the API key/endpoint configuration is incorrect, leading to a resource not found (404) error for the requested functionality.
fixVerify that your OpenAI API key and base URL (for Azure OpenAI, `azure_endpoint` and `api_version`) are correctly configured and that the specified model supports OpenAI's function-calling API. For Azure OpenAI, ensure the `api_version` is `2023-07-01-preview` or newer, as older versions might not support tool calls.
Upgrade
Version history
0.4.12latest on PyPI · released Jun 29, 2025
Audit
Dependencies
llama-index>=0.10.12requiredCore LlamaIndex framework functionality, including agents and tools.
openai>=1.1.0requiredRequired for interacting with OpenAI API, including chat completions and function calling.