Whether you are building AI applications or automating complex tasks, making an AI agent work with the right data and tools can be challenging. Simple AI systems often struggle when they need to reason, retrieve information, or handle tasks across different sources. LlamaIndex agents make this easier by connecting AI models with tools, data, and retrieval systems to handle tasks more effectively. Read this article to learn how to build and deploy LlamaIndex agent workflow for smarter and more flexible AI applications.
What is a LlamaIndex agent?
A LlamaIndex agent is an AI system that can reason about a task and decide what steps are needed to complete it. It can break a complex request into smaller tasks, select tools, and use external data when needed. Agents can also remember previous steps and use retrieved information to improve their responses. This lets them handle tasks that require more than a simple question-and-answer response.
How do LlamaIndex agents work?
LlamaIndex agents enable LLM applications to move beyond simple question answering by allowing models to reason about tasks, select tools, and complete multi-step workflows. Instead of following a fixed pipeline, an agent dynamically decides what actions are needed based on the user's goal and available capabilities.
A typical LlamaIndex agent workflow follows this process:
User request
↓
Understand the task
↓
Select tools
↓
Execute actions
↓
Process results
↓
Return final responseUnderstand user goals
When an agent receives a request, the underlying LLM analyzes the task, available context, and connected tools to determine the best approach.
For simple queries, the agent may generate a response directly. For complex tasks, it can break the request into smaller steps and decide which operations are required.
Select and use tools
Tools extend an agent's capabilities beyond the LLM itself. LlamaIndex agents can connect to custom Python functions, query engines, APIs, databases, and retrieval systems through tools such as FunctionTool and QueryEngineTool.
For example, an agent can use a search tool to gather information, a database tool to retrieve records, or a custom function to perform calculations.
Execute tasks through an agent loop
After selecting a tool, the agent executes the action, observes the result, and decides the next step. This reasoning-action loop allows agents to handle complex workflows that require multiple operations.
Reason → Act → Observe → RepeatIf the task is not complete, the agent can continue calling tools or refining its approach until it generates a final answer.
Manage context and workflows
LlamaIndex agents keep relevant context throughout the execution process, which helps them manage multi-step tasks and use results from earlier steps. For more complex applications, developers can use workflows and multi-agent architectures to coordinate multiple agents, with each agent handling a specific role or task.
For example:
Research Agent
↓
Analysis Agent
↓
Writing AgentThis makes LlamaIndex react agents suitable for applications such as AI research assistants, enterprise knowledge systems, and automated data workflows.
Core components of LlamaIndex agents
LlamaIndex multi-agents combine several components to turn an LLM into a system that can reason, use external functions, and maintain context. Each component has a different role, but they work together to help the agent handle tasks more effectively. Here are some of its core components:
LLM: The reasoning engine of agents
The LLM acts as the main reasoning engine that interprets user requests and decides what to do next. It can analyze the available context and determine whether to answer directly or use a tool. LlamaIndex supports different LLM providers, letting developers choose a model based on their application needs. The LLM therefore controls the agent's decision-making and response generation.
Tools: Extending agent capabilities
Tools allow an agent to perform actions that go beyond generating text. They can be simple Python functions or specialized tools for working with APIs, query engines, and other external services. The agent decides which tool to use and provides the required inputs based on the user's request. Tool results are then added to the conversation so the agent can use them in the next step.
Memory: Maintaining context
Memory allows LlamaIndex agents to retain relevant information while completing a task. By default, agents use a ChatMemoryBuffer, which keeps conversation history available during execution. Developers can also customize the memory configuration, such as setting a token limit based on the application. This helps agents maintain context and handle tasks that require multiple steps.
Types of LlamaIndex agents
LlamaIndex offers different agent types for handling tasks based on the level of reasoning, tool use, and control required. Let's look at the main types and how they differ:
| Agent type | How it works | Key features | Best use cases |
|---|---|---|---|
| FunctionAgent | Uses the function-calling capabilities of modern LLMs to select and execute predefined tools based on user requests. | Native tool calling Structured inputs and outputs Reliable tool execution Simple implementation | AI assistants Business automation workflows API-based applications Task-oriented agents |
| ReActAgent | Uses the Reasoning + Acting approach, where the agent iteratively reasons about a task, takes actions, observes results, and continues until completion. | Step-by-step reasoning Dynamic tool selection Handles multi-step tasks Flexible problem solving | Research assistants Complex question answering Data exploration Open-ended workflows |
| CodeActAgent | Allows agents to solve tasks by generating and executing code when code-based reasoning is more effective. | Code generation and execution Programmatic problem solving Suitable for computational tasks | Data analysis Scientific workflows Programming assistants |
| Multi-agent systems | Uses multiple specialized agents that collaborate, delegate tasks, and complete complex workflows together. | Agent collaboration Task delegation Role specialization Scalable workflows | Automated research pipelines Enterprise workflows Complex business processes |
These agents give developers flexibility to choose the right approach for different tasks and workflows. Once the agent type is selected, the next step is connecting it to a capable LLM backend that can power its reasoning and tool use. Let's see how you can build AI agents with LlamaIndex and the Kimi API.
How to Build AI Agents with LlamaIndex and Kimi API?
Connecting LlamaIndex to an LLM API gives the agent the reasoning power it needs to understand requests and choose the right actions. The following steps show how to set up an AI agent with LlamaIndex and the Kimi API, from configuring the model to running the agent:
Step 1: Prerequisites
Before you begin, ensure you have the following:
Python 3.9+ installed
A valid Kimi API Key from Moonshot AI Platform
Basic familiarity with LlamaIndex agents and RAG concepts
Step 2: Install dependencies
The original example uses llama-index-llms-ollama. Replace it with llama-index-llms-openai to connect to Kimi's OpenAI-compatible API. Keep the HuggingFace embedding package for local, free embeddings.
pip install llama-index llama-index-llms-openai llama-index-embeddings-huggingfaceStep 3: Configure environment variables
Store your Kimi API key securely using an environment variable. Do not hardcode it in your scripts.
export KIMI_API_KEY = "your-kimi-api-key-here"On Windows (PowerShell):
$env:KIMI_API_KEY = "your-kimi-api-key-here"Step 4: Create the basic agent with the Kimi API
Create a file named starter_kimi.py. This replaces the Ollama LLM with Kimi while preserving the same agent logic and tool definitions.
from llama_index.core.agent.workflow import FunctionAgent; import os
from llama_index.llms.openai import OpenAI; import asyncio
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
# Configure global settings
Settings.llm = OpenAI(
model="kimi-latest", # Or: kimi-k2, kimi-k2.5, etc.
api_key=os.getenv("KIMI_API_KEY"),
api_base="https://api.moonshot.ai/v1",
temperature=0.3,
request_timeout=120.0,
)
Settings.embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-base-en-v1.5"
)
# Define a calculator tool
def multiply(a: float, b: float) -> float:
"""Useful for multiplying two numbers."""
return a * b
# Create the agent
agent = FunctionAgent(
tools=[multiply],
llm=Settings.llm,
system_prompt="You are a helpful assistant that can multiply two numbers.",
)
async def main():
response = await agent.run("What is 1234 * 4567?")
print(str(response))
if __name__ == "__main__":
asyncio.run(main())Run the script:
python starter_kimi.pyExpected output:
The answer to 1234 * 4567 is 5635678.Step 5: Add chat history (context)
To enable multi-turn conversations, pass a Context object. The agent will retain memory across calls.
from llama_index.core.workflow import Context
# Create context
ctx = Context(agent)
# Run agent with context
response = await agent.run("My name is Logan", ctx=ctx)
print(response)
response = await agent.run("What is my name?", ctx=ctx)
print(response)Step 6: Add RAG Capabilities with Kimi API
Enhance the agent with document retrieval. The embedding step remains local, while generation routes through Kimi.
Prepare sample data
mkdir data
wget https://raw.githubusercontent.com/run-llama/llama_index/main/docs/examples/data/paul_graham/paul_graham_essay.txt -O data/paul_graham_essay.txtFull RAG-enabled agent script
Create starter_kimi_rag.py:
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings; import os
from llama_index.core.agent.workflow import AgentWorkflow; import asyncio
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
# Global settings
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-base-en-v1.5")
Settings.llm = OpenAI(
model="kimi-k3",
api_key=os.getenv("KIMI_API_KEY"),
api_base="https://api.moonshot.ai/v1",
temperature=0.3,
)
# Load documents and build index
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()
# Define tools
def multiply(a: float, b: float) -> float:
"""Useful for multiplying two numbers."""
return a * b
async def search_documents(query: str) -> str:
"""Useful for answering natural language questions about Paul Graham's essay."""
response = await query_engine.aquery(query)
return str(response)
# Create enhanced agent
agent = AgentWorkflow.from_tools_or_functions(
[multiply, search_documents],
llm=Settings.llm,
system_prompt="""You are a helpful assistant that can perform calculations
and search through documents to answer questions.""",
)
async def main():
response = await agent.run(
"What did the author do in college? Also, what's 7 * 8?"
)
print(response)
if __name__ == "__main__":
asyncio.run(main())Run the script:
python starter_kimi_rag.pypython starter_kimi_rag.pyStep 7: Persist the RAG Index
To avoid reprocessing documents on every run, persist the vector index to disk.
# Save the index
index.storage_context.persist("storage")
# Later, load the index
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine()# Save the index
index.storage_context.persist("storage")
# Later, load the index
from llama_index.core import StorageContext, load_index_from_storage
storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine()Troubleshooting
If you run into issues while setting up the agent, a few common problems can affect authentication, connectivity, package installation, or embedding speed. The table below highlights the most common errors and their solutions, so you can quickly troubleshoot your setup:
| Issue | Cause | Solution |
|---|---|---|
AuthenticationError | Invalid or missing API key | Verify KIMI_API_KEY is exported correctly |
Connection timeout | Network latency to api.moonshot.ai | Increase request_timeout to 300.0 or higher |
ModuleNotFoundError | Missing package | Re-run pip install llama-index-llms-openai |
| Embedding is slow on CPU | Hugging Face model running on CPU | Use a smaller model or enable GPU acceleration |
Benefits of using Kimi API
Once the agent is connected and working, the combination of LlamaIndex and Kimi API offers several practical advantages for building capable AI applications. Here are some key benefits of using Kimi API with LlamaIndex agents:
Build smarter AI agents: Kimi API enhances LlamaIndex agents with strong language understanding and reasoning capabilities, helping agents select tools, process information, and complete tasks more effectively.
Improve data retrieval and analysis: Combined with LlamaIndex's data framework, Kimi can work with private documents and knowledge bases to generate more accurate, context-aware responses.
Enable flexible AI workflows: LlamaIndex connects agents with tools, APIs, and query engines, while Kimi provides the intelligence needed to decide when and how to use these capabilities.
Support complex AI applications: With long-context understanding and agent capabilities, the Kimi API with LlamaIndex is suitable for building research assistants, knowledge agents, and document analysis applications.
Real-world applications of LlamaIndex agents
LlamaIndex agents can be used for a wide range of tasks where AI needs to reason, access information, and take actions. Their ability to connect LLMs with tools and data makes them useful across research, business, analytics, and customer support. Here are some practical applications:
AI research assistant
An AI research assistant can search through documents, retrieve relevant information, and help answer complex questions. It can break a research task into smaller steps and use different tools when needed. This makes it easier to analyze large amounts of information and prepare detailed responses.
Enterprise knowledge agent
An enterprise knowledge agent can connect employees with internal documents, databases, and knowledge bases. It can retrieve relevant company information and provide answers based on available business data. This helps employees find information faster without searching through multiple systems manually.
Data analysis agent
A data analysis agent can work with datasets and use tools to process, analyze, and interpret information. It can perform calculations, identify patterns, and help explain results in a simple way. This makes it useful for tasks such as reporting, data exploration, and business analysis.
Customer service agent
A customer service agent can access product information, FAQs, and support resources to respond to customer questions. It can use tools to retrieve relevant details and handle requests based on the available context. This can help automate routine support tasks while providing faster and consistent responses.
Conclusion
LlamaIndex agents provide a practical way to build AI systems that can reason, use tools, and work with relevant information. Their flexibility makes them useful for creating applications that go beyond simple conversations. With the right LLM backend, these agents can be adapted to different tasks and workflows. Try Kimi API with LlamaIndex to build and test your own AI agent. Explore Kimi and see what you can create with it.