How to build a first LlamaIndex agent

LlamaIndex describes an agent as a semi-autonomous piece of software powered by an LLM. You give it a task. It takes a series of steps, and at each step it selects the best tool it has been given. A tool can be anything from an arbitrary function up to a full LlamaIndex query engine. When a step finishes, the agent judges whether the task is complete. If it is, the agent returns a result. If it is not, the agent loops back to the start.

You do not have to build that loop yourself for a first agent, and you do not need a multi-agent setup. The Python docs let you write agentic workflows from scratch, or use a pre-built workflow. FunctionAgent is the simple function-calling agent. AgentWorkflow is the one that can manage multiple agents. This walkthrough follows only the FunctionAgent tutorial: a virtual environment, two math tools, gpt-4o-mini, and one async question.

Start a clean environment

The page says the tutorial code is also in the agents tutorial repository. To avoid conflicts, it starts a new Python virtual environment. Any environment manager works. The docs use Poetry:

poetry init
poetry shell

Then install the core library, the OpenAI LLM package, and python-dotenv:

pip install llama-index-core llama-index-llms-openai python-dotenv

If that install fails, the same page points you to a longer installation guide. It does not add extra flags here.

Put an OpenAI key in .env

The sample agent is powered by OpenAI's gpt-4o-mini, so you need an API key. The docs put it in a .env file at the project root:

OPENAI_API_KEY=sk-proj-xxxx

That value is the placeholder printed in the docs. Replace it with your own key before you run the agent.

OpenAI is not required. The page says you can use any other LLM, including local models. It also says agents require capable models, so smaller models may be less reliable. Named API alternatives on that page are Mistral, Claude from Anthropic, and Gemini from Google. The tutorial constructor itself still uses gpt-4o-mini.

Import the agent

Load the environment file, then import OpenAI and FunctionAgent:

from dotenv import load_dotenv

load_dotenv()

from llama_index.llms.openai import OpenAI
from llama_index.core.agent.workflow import FunctionAgent

Add two plain functions

The example tools are regular Python functions. One multiplies. One adds. When the agent chooses a tool, it uses the tool name, the parameters, and the docstring to decide what the tool does and whether it fits the task. It also uses the type hints for the expected parameters and return type. The docs say the docstrings should be descriptive.

def multiply(a: float, b: float) -> float:
    """Multiply two numbers and returns the product"""
    return a * b

def add(a: float, b: float) -> float:
    """Add two numbers and returns the sum"""
    return a + b

Keep those docstrings. They are part of the selection step, not comments you can drop.

Initialize the model and FunctionAgent

Create the LLM, then pass an array of tools, the LLM, and a system prompt. The prompt tells the agent what kind of agent to be. The page notes that a real system prompt would usually be more detailed than this one.

llm = OpenAI(model="gpt-4o-mini")

workflow = FunctionAgent(
    tools=[multiply, add],
    llm=llm,
    system_prompt="You are an agent that can perform basic mathematical operations using tools.",
)

The docs also note that gpt-4o-mini is smart enough to do this simple math without tools, which is why the prompt says to use them.

FunctionAgent is not the only agent class on that page. ReActAgent and CodeActAgent use different prompting strategies to execute tools. Neither is required for this first run.

Ask one async question

The sample question needs both operations. The notebook form is:

response = await workflow.run(user_msg="What is 20+(2*4)?")
print(response)

That call is asynchronous. It works as written in a notebook. In a normal Python script, wrap it in an async function:

async def main():
    response = await workflow.run(user_msg="What is 20+(2*4)?")
    print(response)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

The page says this should give output similar to:

The result of (20 + (2 times 4)) is 28.

Similar is the word the docs use. Do not require that exact sentence. The documented result is 28.

The same page points at 1_basic_agent.py in the agents tutorial repository for the finished file. After this basic agent, the docs move on to pre-built tools.

TypeScript is an alternate, not a second tutorial

LlamaIndex.TS has a separate basic-agent page. Use it only if you are not following the Python path. The page also recommends a longer, step-by-step TypeScript agents guide for what agents are and how to build them for production. The basic file is the short version.

In a new folder, that page runs:

npm init
npm i -D typescript @types/node
npm i @llamaindex/openai @llamaindex/workflow llamaindex zod

You create example.ts. The page says that file creates a sumNumbers tool that adds two numbers and a divideNumbers tool that divides numbers, gives an example of the data structure to generate, and prompts the LLM with instructions, that example, and a sample transcript. The implementation is referenced from the page and is not printed there, so it is not reconstructed here.

Run the file with:

npx tsx example.ts

The page prints a sample object, then the word Done. In that object, the result text says five plus five is ten, then ten divided by two is five. The state includes memory, an empty scratchpad, and a current agent name of Agent.

What to run next

Run the Python script and compare the printed answer with the sample on the building-an-agent page, which reports a result of 28 for the question passed to the async run call. Then stay on that page and continue to pre-built tools. Open the TypeScript basic-agent page only if you are switching stacks.

Sources

• Building an agent
• Basic Agent