Seja para criar aplicações de IA ou automatizar tarefas complexas, fazer um agente de IA funcionar com os dados e ferramentas certos pode ser desafiador. Sistemas de IA simples costumam ter dificuldades quando precisam raciocinar, recuperar informações ou lidar com tarefas em diferentes fontes. Os agentes do LlamaIndex facilitam isso ao conectar modelos de IA a ferramentas, dados e sistemas de recuperação para lidar com tarefas de forma mais eficaz. Leia este artigo para aprender a criar e implantar um workflow de agente LlamaIndex para aplicações de IA mais inteligentes e flexíveis.
O que é um agente LlamaIndex?
Um agente LlamaIndex é um sistema de IA capaz de raciocinar sobre uma tarefa e decidir quais etapas são necessárias para concluí-la. Ele pode dividir uma solicitação complexa em tarefas menores, selecionar ferramentas e usar dados externos quando necessário. Os agentes também podem lembrar etapas anteriores e usar informações recuperadas para melhorar suas respostas. Isso permite que lidem com tarefas que exigem mais do que uma simples resposta de pergunta e resposta.
Como funcionam os agentes do LlamaIndex?
Os agentes do LlamaIndex permitem que aplicações de LLM vão além de simples respostas a perguntas, permitindo que os modelos raciocinem sobre tarefas, selecionem ferramentas e concluam workflows de várias etapas. Em vez de seguir um pipeline fixo, um agente decide dinamicamente quais ações são necessárias com base no objetivo do usuário e nas capacidades disponíveis.
Um workflow típico de agente LlamaIndex segue este processo:
User request
↓
Understand the task
↓
Select tools
↓
Execute actions
↓
Process results
↓
Return final responseEntender os objetivos do usuário
Quando um agente recebe uma solicitação, o LLM subjacente analisa a tarefa, o contexto disponível e as ferramentas conectadas para determinar a melhor abordagem.
Para consultas simples, o agente pode gerar uma resposta diretamente. Para tarefas complexas, ele pode dividir a solicitação em etapas menores e decidir quais operações são necessárias.
Selecionar e usar ferramentas
As ferramentas estendem as capacidades de um agente além do próprio LLM. Os agentes do LlamaIndex podem se conectar a funções Python personalizadas, mecanismos de consulta, APIs, bancos de dados e sistemas de recuperação por meio de ferramentas como FunctionTool e QueryEngineTool.
Por exemplo, um agente pode usar uma ferramenta de busca para coletar informações, uma ferramenta de banco de dados para recuperar registros ou uma função personalizada para realizar cálculos.
Executar tarefas por meio de um loop de agente
Depois de selecionar uma ferramenta, o agente executa a ação, observa o resultado e decide a próxima etapa. Esse loop de raciocínio e ação permite que os agentes lidem com workflows complexos que exigem várias operações.
Reason → Act → Observe → RepeatSe a tarefa não estiver concluída, o agente pode continuar chamando ferramentas ou refinando sua abordagem até gerar uma resposta final.
Gerenciar contexto e workflows
Os agentes do LlamaIndex mantêm o contexto relevante durante todo o processo de execução, o que os ajuda a gerenciar tarefas de várias etapas e usar resultados de etapas anteriores. Para aplicações mais complexas, os desenvolvedores podem usar workflows e arquiteturas multiagente para coordenar vários agentes, cada um responsável por um papel ou tarefa específica.
Por exemplo:
Research Agent
↓
Analysis Agent
↓
Writing AgentIsso torna os agentes react do LlamaIndex adequados para aplicações como assistentes de pesquisa de IA, sistemas de conhecimento corporativo e workflows automatizados de dados.
Componentes principais dos agentes do LlamaIndex
Os multiagentes do LlamaIndex combinam vários componentes para transformar um LLM em um sistema capaz de raciocinar, usar funções externas e manter contexto. Cada componente tem um papel diferente, mas eles trabalham juntos para ajudar o agente a lidar com tarefas de forma mais eficaz. Veja alguns de seus componentes principais:
LLM: o motor de raciocínio dos agentes
O LLM atua como o principal motor de raciocínio que interpreta as solicitações do usuário e decide o que fazer a seguir. Ele pode analisar o contexto disponível e determinar se deve responder diretamente ou usar uma ferramenta. O LlamaIndex oferece suporte a diferentes provedores de LLM, permitindo que os desenvolvedores escolham um modelo com base nas necessidades da sua aplicação. Assim, o LLM controla a tomada de decisão e a geração de respostas do agente.
Ferramentas: ampliando as capacidades do agente
As ferramentas permitem que um agente realize ações que vão além de gerar texto. Podem ser funções Python simples ou ferramentas especializadas para trabalhar com APIs, mecanismos de consulta e outros serviços externos. O agente decide qual ferramenta usar e fornece as entradas necessárias com base na solicitação do usuário. Os resultados das ferramentas são então adicionados à conversa para que o agente possa usá-los na próxima etapa.
Memória: mantendo o contexto
A memória permite que os agentes do LlamaIndex retenham informações relevantes enquanto concluem uma tarefa. Por padrão, os agentes usam um ChatMemoryBuffer, que mantém o histórico de conversa disponível durante a execução. Os desenvolvedores também podem personalizar a configuração de memória, como definir um limite de tokens com base na aplicação. Isso ajuda os agentes a manter o contexto e lidar com tarefas que exigem várias etapas.
Tipos de agentes do LlamaIndex
O LlamaIndex oferece diferentes tipos de agentes para lidar com tarefas com base no nível de raciocínio, uso de ferramentas e controle necessário. Vamos ver os principais tipos e como eles se diferenciam:
| Tipo de agente | Como funciona | Principais recursos | Melhores casos de uso |
|---|---|---|---|
| FunctionAgent | Usa os recursos de chamada de função dos LLMs modernos para selecionar e executar ferramentas predefinidas com base nas solicitações do usuário. | Chamada de função nativa Entradas e saídas estruturadas Execução confiável de ferramentas Implementação simples | Assistentes de IA Fluxos de automação empresarial Aplicações baseadas em API Agentes orientados a tarefas |
| ReActAgent | Usa a abordagem de Raciocínio + Ação, na qual o agente raciocina iterativamente sobre uma tarefa, realiza ações, observa os resultados e continua até a conclusão. | Raciocínio passo a passo Seleção dinâmica de ferramentas Lida com tarefas de múltiplas etapas Resolução flexível de problemas | Assistentes de pesquisa Respostas a perguntas complexas Exploração de dados Fluxos de trabalho abertos |
| CodeActAgent | Permite que os agentes resolvam tarefas gerando e executando código quando o raciocínio baseado em código é mais eficaz. | Geração e execução de código Resolução programática de problemas Adequado para tarefas computacionais | Análise de dados Fluxos de trabalho científicos Assistentes de programação |
| Sistemas multiagente | Usa vários agentes especializados que colaboram, delegam tarefas e concluem fluxos de trabalho complexos em conjunto. | Colaboração entre agentes Delegação de tarefas Especialização de funções Fluxos de trabalho escaláveis | Pipelines de pesquisa automatizados Fluxos de trabalho corporativos Processos de negócios complexos |
Esses agentes dão aos desenvolvedores flexibilidade para escolher a abordagem certa para diferentes tarefas e workflows. Depois de selecionar o tipo de agente, a próxima etapa é conectá-lo a um backend de LLM capaz de alimentar seu raciocínio e uso de ferramentas. Vamos ver como você pode criar agentes de IA com o LlamaIndex e a Kimi API.
Como criar agentes de IA com LlamaIndex e Kimi API?
Conectar o LlamaIndex a uma API de LLM dá ao agente o poder de raciocínio necessário para entender solicitações e escolher as ações certas. As etapas a seguir mostram como configurar um agente de IA com o LlamaIndex e a Kimi API, desde a configuração do modelo até a execução do agente:
Etapa 1: Pré-requisitos
Antes de começar, certifique-se de que você tem o seguinte:
Python 3.9+ instalado
Uma chave de API Kimi válida obtida na Moonshot AI Platform
Familiaridade básica com agentes LlamaIndex e conceitos de RAG
Etapa 2: Instalar as dependências
O exemplo original usa llama-index-llms-ollama. Substitua por llama-index-llms-openai para se conectar à API compatível com OpenAI da Kimi. Mantenha o pacote de embeddings da HuggingFace para embeddings locais e gratuitos.
pip install llama-index llama-index-llms-openai llama-index-embeddings-huggingfaceEtapa 3: Configurar variáveis de ambiente
Armazene sua chave de API Kimi de forma segura usando uma variável de ambiente. Não a fixe diretamente nos seus scripts.
export KIMI_API_KEY = "your-kimi-api-key-here"No Windows (PowerShell):
$env:KIMI_API_KEY = "your-kimi-api-key-here"Etapa 4: Criar o agente básico com a API Kimi
Crie um arquivo chamado starter_kimi.py. Ele substitui o LLM da Ollama pelo Kimi, mantendo a mesma lógica do agente e as mesmas definições de ferramentas.
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())Execute o script:
python starter_kimi.pySaída esperada:
The answer to 1234 * 4567 is 5635678.Etapa 5: Adicionar histórico de conversa (contexto)
Para habilitar conversas com múltiplos turnos, passe um objeto Context. O agente manterá a memória entre as chamadas.
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)Etapa 6: Adicionar capacidades de RAG com a API Kimi
Aprimore o agente com recuperação de documentos. A etapa de embedding continua local, enquanto a geração passa pela Kimi.
Preparar dados de exemplo
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.txtScript completo do agente com RAG habilitado
Crie 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())Execute o script:
python starter_kimi_rag.pypython starter_kimi_rag.pyEtapa 7: Persistir o índice de RAG
Para evitar reprocessar os documentos a cada execução, persista o índice vetorial em disco.
# 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()Solução de problemas
Se você tiver problemas ao configurar o agente, alguns problemas comuns podem afetar a autenticação, a conectividade, a instalação de pacotes ou a velocidade de embedding. A tabela abaixo destaca os erros mais comuns e suas soluções, para que você possa resolver rapidamente a sua configuração:
| Problema | Causa | Solução |
|---|---|---|
AuthenticationError | Chave de API inválida ou ausente | Verifique se a KIMI_API_KEY foi exportada corretamente |
Connection timeout | Latência de rede até api.moonshot.ai | Aumente o request_timeout para 300.0 ou mais |
ModuleNotFoundError | Pacote ausente | Execute novamente pip install llama-index-llms-openai |
| O embedding está lento na CPU | Modelo do Hugging Face em execução na CPU | Use um modelo menor ou ative a aceleração por GPU |
Benefícios de usar a API Kimi
Uma vez que o agente esteja conectado e funcionando, a combinação de LlamaIndex e API Kimi oferece diversas vantagens práticas para a criação de aplicações de IA capazes. Veja alguns benefícios importantes de usar a API Kimi com agentes LlamaIndex:
Crie agentes de IA mais inteligentes: a API Kimi aprimora os agentes LlamaIndex com forte compreensão de linguagem e capacidade de raciocínio, ajudando os agentes a selecionar ferramentas, processar informações e concluir tarefas com mais eficácia.
Melhore a recuperação e análise de dados: combinado com o framework de dados do LlamaIndex, o Kimi pode trabalhar com documentos privados e bases de conhecimento para gerar respostas mais precisas e sensíveis ao contexto.
Viabilize fluxos de trabalho de IA flexíveis: o LlamaIndex conecta agentes a ferramentas, APIs e mecanismos de consulta, enquanto o Kimi fornece a inteligência necessária para decidir quando e como usar esses recursos.
Suporte a aplicações de IA complexas: com compreensão de contexto longo e capacidades de agente, a API Kimi com LlamaIndex é adequada para criar assistentes de pesquisa, agentes de conhecimento e aplicações de análise de documentos.
Aplicações reais dos agentes LlamaIndex
Os agentes LlamaIndex podem ser usados em uma ampla gama de tarefas em que a IA precisa raciocinar, acessar informações e agir. Sua capacidade de conectar LLMs a ferramentas e dados os torna úteis em pesquisa, negócios, análise de dados e atendimento ao cliente. Veja algumas aplicações práticas:
Assistente de pesquisa com IA
Um assistente de pesquisa com IA pode buscar em documentos, recuperar informações relevantes e ajudar a responder questões complexas. Ele pode dividir uma tarefa de pesquisa em etapas menores e usar diferentes ferramentas quando necessário. Isso facilita a análise de grandes volumes de informação e a preparação de respostas detalhadas.
Agente de conhecimento corporativo
Um agente de conhecimento corporativo pode conectar os funcionários a documentos internos, bancos de dados e bases de conhecimento. Ele pode recuperar informações relevantes da empresa e fornecer respostas com base nos dados de negócio disponíveis. Isso ajuda os funcionários a encontrar informações mais rapidamente, sem precisar buscar manualmente em vários sistemas.
Agente de análise de dados
Um agente de análise de dados pode trabalhar com conjuntos de dados e usar ferramentas para processar, analisar e interpretar informações. Ele pode realizar cálculos, identificar padrões e ajudar a explicar resultados de forma simples. Isso o torna útil para tarefas como geração de relatórios, exploração de dados e análise de negócios.
Agente de atendimento ao cliente
Um agent de atendimento ao cliente pode acessar informações de produtos, FAQs e recursos de suporte para responder às perguntas dos clientes. Ele pode usar ferramentas para recuperar detalhes relevantes e tratar solicitações com base no contexto disponível. Isso pode ajudar a automatizar tarefas rotineiras de suporte, oferecendo respostas mais rápidas e consistentes.
Conclusão
Os agents do LlamaIndex oferecem uma forma prática de construir sistemas de IA capazes de raciocinar, usar ferramentas e trabalhar com informações relevantes. Sua flexibilidade os torna úteis para criar aplicações que vão além de simples conversas. Com o backend de LLM certo, esses agents podem ser adaptados a diferentes tarefas e fluxos de trabalho. Experimente a Kimi API com o LlamaIndex para criar e testar seu próprio agent de IA. Explore o Kimi e veja o que você pode criar com ele.