Che tu stia costruendo applicazioni di AI o automatizzando attività complesse, far funzionare un agente AI con i dati e i tool giusti può essere impegnativo. I sistemi AI semplici spesso hanno difficoltà quando devono ragionare, recuperare informazioni o gestire attività provenienti da fonti diverse. Gli agenti LlamaIndex rendono tutto questo più semplice collegando i modelli AI a tool, dati e sistemi di recupero per gestire le attività in modo più efficace. Leggi questo articolo per scoprire come costruire e implementare un workflow di agenti LlamaIndex per applicazioni AI più intelligenti e flessibili.
Cos'è un agente LlamaIndex?
Un agente LlamaIndex è un sistema AI in grado di ragionare su un'attività e decidere quali passaggi sono necessari per completarla. Può suddividere una richiesta complessa in attività più piccole, selezionare tool e utilizzare dati esterni quando necessario. Gli agenti possono anche ricordare i passaggi precedenti e utilizzare le informazioni recuperate per migliorare le loro risposte. Questo permette loro di gestire attività che richiedono più di una semplice risposta a una domanda.
Come funzionano gli agenti LlamaIndex?
Gli agenti LlamaIndex consentono alle applicazioni LLM di andare oltre la semplice risposta alle domande, permettendo ai modelli di ragionare sulle attività, selezionare tool e completare workflow a più passaggi. Invece di seguire una pipeline fissa, un agente decide dinamicamente quali azioni sono necessarie in base all'obiettivo dell'utente e alle capacità disponibili.
Un tipico workflow di un agente LlamaIndex segue questo processo:
User request
↓
Understand the task
↓
Select tools
↓
Execute actions
↓
Process results
↓
Return final responseComprendere gli obiettivi dell'utente
Quando un agente riceve una richiesta, l'LLM sottostante analizza l'attività, il contesto disponibile e i tool collegati per determinare l'approccio migliore.
Per query semplici, l'agente può generare direttamente una risposta. Per attività complesse, può suddividere la richiesta in passaggi più piccoli e decidere quali operazioni sono necessarie.
Selezionare e utilizzare i tool
I tool estendono le capacità di un agente oltre l'LLM stesso. Gli agenti LlamaIndex possono connettersi a funzioni Python personalizzate, motori di query, API, database e sistemi di recupero tramite tool come FunctionTool e QueryEngineTool.
Ad esempio, un agente può utilizzare un tool di ricerca per raccogliere informazioni, un tool per database per recuperare record o una funzione personalizzata per eseguire calcoli.
Eseguire attività tramite un ciclo dell'agente
Dopo aver selezionato un tool, l'agente esegue l'azione, osserva il risultato e decide il passaggio successivo. Questo ciclo di ragionamento-azione permette agli agenti di gestire workflow complessi che richiedono più operazioni.
Reason → Act → Observe → RepeatSe l'attività non è completa, l'agente può continuare a chiamare tool o perfezionare il proprio approccio fino a generare una risposta finale.
Gestire contesto e workflow
Gli agenti LlamaIndex mantengono il contesto rilevante durante l'intero processo di esecuzione, il che li aiuta a gestire attività a più passaggi e a utilizzare i risultati dei passaggi precedenti. Per applicazioni più complesse, gli sviluppatori possono utilizzare workflow e architetture multi-agente per coordinare più agenti, con ciascun agente che gestisce un ruolo o un'attività specifica.
Ad esempio:
Research Agent
↓
Analysis Agent
↓
Writing AgentQuesto rende gli agenti react di LlamaIndex adatti per applicazioni come assistenti di ricerca AI, sistemi di conoscenza aziendale e workflow di dati automatizzati.
Componenti principali degli agenti LlamaIndex
I multi-agenti LlamaIndex combinano diversi componenti per trasformare un LLM in un sistema capace di ragionare, utilizzare funzioni esterne e mantenere il contesto. Ogni componente ha un ruolo diverso, ma lavorano insieme per aiutare l'agente a gestire le attività in modo più efficace. Ecco alcuni dei suoi componenti principali:
LLM: il motore di ragionamento degli agenti
L'LLM agisce come il motore di ragionamento principale che interpreta le richieste dell'utente e decide cosa fare successivamente. Può analizzare il contesto disponibile e determinare se rispondere direttamente o utilizzare un tool. LlamaIndex supporta diversi provider LLM, permettendo agli sviluppatori di scegliere un modello in base alle esigenze della propria applicazione. L'LLM controlla quindi il processo decisionale dell'agente e la generazione delle risposte.
Tool: estendere le capacità dell'agente
I tool permettono a un agente di eseguire azioni che vanno oltre la generazione di testo. Possono essere semplici funzioni Python o tool specializzati per lavorare con API, motori di query e altri servizi esterni. L'agente decide quale tool utilizzare e fornisce gli input richiesti in base alla richiesta dell'utente. I risultati dei tool vengono quindi aggiunti alla conversazione affinché l'agente possa utilizzarli nel passaggio successivo.
Memoria: mantenere il contesto
La memoria permette agli agenti LlamaIndex di conservare le informazioni rilevanti durante l'esecuzione di un'attività. Per impostazione predefinita, gli agenti utilizzano un ChatMemoryBuffer, che mantiene disponibile la cronologia della conversazione durante l'esecuzione. Gli sviluppatori possono anche personalizzare la configurazione della memoria, ad esempio impostando un limite di token in base all'applicazione. Questo aiuta gli agenti a mantenere il contesto e a gestire attività che richiedono più passaggi.
Tipi di agenti LlamaIndex
LlamaIndex offre diversi tipi di agenti per gestire le attività in base al livello di ragionamento, utilizzo dei tool e controllo richiesto. Vediamo i tipi principali e come differiscono:
| Tipo di agente | Come funziona | Caratteristiche principali | Casi d'uso migliori |
|---|---|---|---|
| FunctionAgent | Utilizza le capacità di function calling degli LLM moderni per selezionare ed eseguire strumenti predefiniti in base alle richieste dell'utente. | Tool calling nativo Input e output strutturati Esecuzione affidabile degli strumenti Implementazione semplice | Assistenti AI Flussi di automazione aziendale Applicazioni basate su API Agenti orientati a compiti specifici |
| ReActAgent | Utilizza l'approccio Reasoning + Acting, in cui l'agente ragiona in modo iterativo su un compito, compie azioni, osserva i risultati e continua finché il compito non è completato. | Ragionamento passo dopo passo Selezione dinamica degli strumenti Gestione di compiti su più fasi Risoluzione flessibile dei problemi | Assistenti di ricerca Risposta a domande complesse Esplorazione dei dati Flussi di lavoro aperti |
| CodeActAgent | Consente agli agenti di risolvere i compiti generando ed eseguendo codice quando il ragionamento basato sul codice è più efficace. | Generazione ed esecuzione di codice Risoluzione di problemi programmatica Adatto a compiti computazionali | Analisi dei dati Flussi di lavoro scientifici Assistenti alla programmazione |
| Sistemi multi-agente | Utilizza più agenti specializzati che collaborano, delegano compiti e completano insieme flussi di lavoro complessi. | Collaborazione tra agenti Delega dei compiti Specializzazione dei ruoli Flussi di lavoro scalabili | Pipeline di ricerca automatizzate Flussi di lavoro aziendali Processi aziendali complessi |
Questi agenti offrono agli sviluppatori la flessibilità di scegliere l'approccio giusto per attività e workflow diversi. Una volta selezionato il tipo di agente, il passaggio successivo consiste nel collegarlo a un backend LLM capace, in grado di alimentare il suo ragionamento e l'utilizzo dei tool. Vediamo come costruire agenti AI con LlamaIndex e la Kimi API.
Come costruire agenti AI con LlamaIndex e Kimi API?
Collegare LlamaIndex a un'API LLM offre all'agente la capacità di ragionamento necessaria per comprendere le richieste e scegliere le azioni giuste. I seguenti passaggi mostrano come configurare un agente AI con LlamaIndex e la Kimi API, dalla configurazione del modello all'esecuzione dell'agente:
Passaggio 1: prerequisiti
Prima di iniziare, assicurati di avere quanto segue:
Python 3.9+ installato
Una Kimi API Key valida da Moonshot AI Platform
Familiarità di base con gli agent di LlamaIndex e i concetti RAG
Passaggio 2: installa le dipendenze
L'esempio originale usa llama-index-llms-ollama. Sostituiscilo con llama-index-llms-openai per connetterti all'API di Kimi compatibile con OpenAI. Mantieni il package di embedding HuggingFace per embedding locali e gratuiti.
pip install llama-index llama-index-llms-openai llama-index-embeddings-huggingfacePassaggio 3: configura le variabili d'ambiente
Conserva la tua Kimi API key in modo sicuro usando una variabile d'ambiente. Non inserirla direttamente negli script.
export KIMI_API_KEY = "your-kimi-api-key-here"Su Windows (PowerShell):
$env:KIMI_API_KEY = "your-kimi-api-key-here"Passaggio 4: crea l'agent di base con la Kimi API
Crea un file chiamato starter_kimi.py. Questo sostituisce l'LLM Ollama con Kimi, mantenendo invariata la logica dell'agent e le definizioni degli strumenti.
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())Esegui lo script:
python starter_kimi.pyOutput previsto:
The answer to 1234 * 4567 is 5635678.Passaggio 5: aggiungi la cronologia della chat (contesto)
Per abilitare conversazioni multi-turno, passa un oggetto Context. L'agent conserverà la memoria tra le chiamate.
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)Passaggio 6: aggiungi funzionalità RAG con la Kimi API
Migliora l'agent con il recupero di documenti. Il passaggio di embedding resta locale, mentre la generazione passa attraverso Kimi.
Prepara i dati di esempio
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 dell'agent con RAG
Crea 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())Esegui lo script:
python starter_kimi_rag.pypython starter_kimi_rag.pyPassaggio 7: rendi persistente l'indice RAG
Per evitare di riprocessare i documenti a ogni esecuzione, rendi persistente l'indice vettoriale su 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()Risoluzione dei problemi
Se incontri problemi durante la configurazione dell'agent, alcuni problemi comuni possono riguardare l'autenticazione, la connettività, l'installazione dei package o la velocità di embedding. La tabella seguente evidenzia gli errori più comuni e le relative soluzioni, così puoi risolvere rapidamente i problemi della tua configurazione:
| Problema | Causa | Soluzione |
|---|---|---|
AuthenticationError | Chiave API non valida o mancante | Verifica che KIMI_API_KEY sia esportata correttamente |
Connection timeout | Latenza di rete verso api.moonshot.ai | Aumenta request_timeout a 300.0 o un valore superiore |
ModuleNotFoundError | Pacchetto mancante | Esegui nuovamente pip install llama-index-llms-openai |
| L'embedding è lento sulla CPU | Modello Hugging Face in esecuzione sulla CPU | Usa un modello più piccolo o attiva l'accelerazione GPU |
Vantaggi dell'uso della Kimi API
Una volta che l'agent è connesso e funzionante, la combinazione di LlamaIndex e Kimi API offre diversi vantaggi pratici per costruire applicazioni AI efficaci. Ecco alcuni vantaggi chiave dell'uso della Kimi API con gli agent di LlamaIndex:
Crea agent AI più intelligenti: la Kimi API potenzia gli agent di LlamaIndex con solide capacità di comprensione del linguaggio e di ragionamento, aiutando gli agent a scegliere gli strumenti, elaborare le informazioni e completare i task in modo più efficace.
Migliora il recupero e l'analisi dei dati: combinato con il framework di dati di LlamaIndex, Kimi può lavorare con documenti privati e basi di conoscenza per generare risposte più accurate e contestualizzate.
Abilita workflow AI flessibili: LlamaIndex collega gli agent a strumenti, API e motori di query, mentre Kimi fornisce l'intelligenza necessaria per decidere quando e come usare queste funzionalità.
Supporta applicazioni AI complesse: grazie alla comprensione del contesto lungo e alle capacità agentiche, la Kimi API con LlamaIndex è adatta per costruire assistenti di ricerca, agenti di conoscenza e applicazioni di analisi dei documenti.
Applicazioni reali degli agent di LlamaIndex
Gli agent di LlamaIndex possono essere usati per un'ampia gamma di task in cui l'AI deve ragionare, accedere alle informazioni e compiere azioni. La loro capacità di collegare gli LLM a strumenti e dati li rende utili nella ricerca, nel business, nell'analisi e nel supporto clienti. Ecco alcune applicazioni pratiche:
Assistente di ricerca AI
Un assistente di ricerca AI può cercare tra i documenti, recuperare informazioni rilevanti e aiutare a rispondere a domande complesse. Può suddividere un task di ricerca in passaggi più piccoli e usare strumenti diversi quando necessario. Questo rende più semplice analizzare grandi quantità di informazioni e preparare risposte dettagliate.
Agent di conoscenza aziendale
Un agent di conoscenza aziendale può collegare i dipendenti a documenti interni, database e basi di conoscenza. Può recuperare informazioni aziendali rilevanti e fornire risposte basate sui dati disponibili. Questo aiuta i dipendenti a trovare informazioni più rapidamente senza dover cercare manualmente in più sistemi.
Agent di analisi dati
Un agent di analisi dati può lavorare con set di dati e usare strumenti per elaborare, analizzare e interpretare le informazioni. Può eseguire calcoli, identificare pattern e aiutare a spiegare i risultati in modo semplice. Questo lo rende utile per attività come la reportistica, l'esplorazione dei dati e l'analisi di business.
Agent di assistenza clienti
Un agent per il servizio clienti può accedere a informazioni sui prodotti, FAQ e risorse di supporto per rispondere alle domande dei clienti. Può usare strumenti per recuperare i dettagli rilevanti e gestire le richieste in base al contesto disponibile. Questo può contribuire ad automatizzare le attività di supporto di routine, offrendo al contempo risposte più rapide e coerenti.
Conclusione
Gli agent di LlamaIndex offrono un modo pratico per costruire sistemi di IA in grado di ragionare, usare strumenti e lavorare con informazioni rilevanti. La loro flessibilità li rende utili per creare applicazioni che vanno oltre le semplici conversazioni. Con il giusto backend LLM, questi agent possono essere adattati a compiti e flussi di lavoro diversi. Prova Kimi API con LlamaIndex per costruire e testare il tuo agent di IA. Scopri Kimi e cosa puoi creare con esso.