LlamaIndex Tutorial (Python): adding tool use for beginners

This tutorial shows you how to add tool use to a LlamaIndex Python agent so it can call external functions instead of guessing. You need this when your app has real work to do, like fetching live data, calculating values, or querying internal systems.

What You'll Need

• •Python 3.10+
• •A virtual environment
• •llama-index
• •An LLM API key, such as OPENAI_API_KEY
• •Basic familiarity with LlamaIndex VectorStoreIndex and chat agents
• •A terminal and a text editor

Install the package first:

pip install llama-index

Set your OpenAI key in your shell:

export OPENAI_API_KEY="your-api-key"

Step-by-Step

1. •Start with a minimal LlamaIndex setup. We’ll create an index from a few documents and keep the agent focused on answering from indexed content plus tools.

from llama_index.core import VectorStoreIndex, Document

docs = [
    Document(text="Topiax builds AI systems for regulated industries."),
    Document(text="LlamaIndex helps connect LLMs to data and tools."),
]

index = VectorStoreIndex.from_documents(docs)
query_engine = index.as_query_engine()

2. •Define a real Python function and wrap it as a tool. This is the part that lets the agent do something deterministic instead of hallucinating an answer.

from llama_index.core.tools import FunctionTool

def calculate_premium(age: int, base_rate: float) -> float:
    """Calculate a simple insurance premium."""
    if age < 25:
        return round(base_rate * 1.25, 2)
    if age > 60:
        return round(base_rate * 1.15, 2)
    return round(base_rate, 2)

premium_tool = FunctionTool.from_defaults(
    fn=calculate_premium,
    name="calculate_premium",
    description="Calculate an insurance premium from age and base rate.",
)

3. •Add another tool that simulates an external lookup. In production this could be a database query, policy admin API call, or internal service request.

def get_policy_status(policy_id: str) -> str:
    """Return a fake policy status for demo purposes."""
    sample = {
        "POL123": "active",
        "POL456": "pending_review",
        "POL789": "lapsed",
    }
    return sample.get(policy_id.upper(), "not_found")

status_tool = FunctionTool.from_defaults(
    fn=get_policy_status,
    name="get_policy_status",
    description="Look up the status of an insurance policy by policy ID.",
)

4. •Create a ReAct-style agent with both tools attached. This gives the model the ability to decide when to answer directly and when to call one of your functions.

from llama_index.core.agent import ReActAgent

agent = ReActAgent.from_tools(
    tools=[premium_tool, status_tool],
    query_engine=query_engine,
    verbose=True,
)

5. •Ask the agent questions that force tool use. Use prompts that clearly require calculation or lookup so you can see the tool calls in action.

response_1 = agent.chat("What is the premium for a 22-year-old with a base rate of 100?")
print(response_1)

response_2 = agent.chat("What is the status of policy POL456?")
print(response_2)

response_3 = agent.chat("What does Topiax do?")
print(response_3)

Testing It

Run the script and watch the verbose output. You should see the agent deciding whether to use calculate_premium or get_policy_status for tool-driven questions, then falling back to indexed knowledge for general questions.

If the premium question returns 125.0, your function wiring is correct. If POL456 returns pending_review, your second tool is working too.

If you get authentication errors, check that OPENAI_API_KEY is set in the same shell session where you run Python.

Next Steps

• •Replace demo functions with real API clients or database queries
• •Learn how to add structured inputs with Pydantic models for safer tool calls
• •Explore memory and routing so agents can choose between multiple indices and tools

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.