Tutorial di Agent Framework

Iniziare a utilizzare un notebook

Inizia a utilizzare Agent Framework utilizzando un agente "Hello World" in un notebook.

Agenti di esempio

Per esaminare il codice di esempio per gli agenti di esempio, scarica il file ZIP da questa cartella di Google Drive nel tuo ambiente di sviluppo locale.

Nella directory samples sono presenti gli agenti demo. Installa le dipendenze nel requirements.txt file per un agente demo specifico:

pip install  -r samples/anthropic_demo/requirements.txt

Esegui questi comandi:

af web samples

af run samples/hello_world

Tutorial

Questa pagina fornisce tutorial passo passo per le attività comuni quando si utilizza Agent Framework. Scegli un tutorial per iniziare.

Tutorial: integrare i tuoi dati in un agente

Questo tutorial illustra diversi metodi per fornire all'agente i tuoi dati, le tue conoscenze o i tuoi documenti. L'approccio migliore dipende dalle dimensioni e dal tipo di dati, nonché dal bilanciamento desiderato tra latenza e precisione.

Fornire i tuoi dati

Esistono diversi modi per fornire all'agente i tuoi dati, le tue conoscenze o i tuoi documenti, in base alle dimensioni e al tipo di dati e al compromesso desiderato tra latenza e accuratezza.

Tipo Importo irrisorio Importo elevato
Testo normale Incorporare nell'istruzione o nel RAG RAG
Documenti Incorporare nell'istruzione o nel RAG RAG
Altri contenuti multimediali
(immagini, audio, video e così via)		 In lavorazione In lavorazione

Le seguenti istruzioni forniscono ulteriori informazioni su ciascun approccio.

Incorporare i dati nelle istruzioni

Un modo semplice per fornire all'agente una piccola quantità di documenti è incorporarli nelle istruzioni.

I file PDF o di testo possono essere convertiti in testo normale e incorporati nelle istruzioni.

Considerazioni

  • I contenuti dei file verranno inviati al modello, quindi più grande è il file, più elevati saranno la latenza e il costo.

  • I contenuti verranno inviati al modello per tutte le richieste, indipendentemente dal fatto che la query dell'utente non abbia nulla a che fare con i contenuti.

  • Puoi utilizzare il testo normale o qualsiasi formato di testo leggibile, ad esempio Markdown, per il tuo file.

Rischi per la sicurezza

  • L'incorporamento dei contenuti in questo modo comporta alcuni rischi per la sicurezza, in quanto il server potrebbe trattare i contenuti dei documenti incorporati come proprie istruzioni.

  • Questo rischio per la sicurezza può essere mitigato in una certa misura indicando chiaramente l'inizio e la fine dei contenuti incorporati, come mostrato nell'esempio seguente.

  • A causa di questo rischio, non incorporare contenuti che non ritieni attendibili, ad esempio contenuti generati dagli utenti.

Esempio

Per rendere leggibili le istruzioni, un approccio comune è caricare il file e inserirlo nelle istruzioni utilizzando la sintassi della stringa f di Python.

Tieni presente che utilizza i tag XML per separare i contenuti del file dal resto delle istruzioni. Puoi utilizzare anche altri modi per separare, purché sia chiaro per il modello. Ad esempio, tag come BEGIN_USER_GUIDE / END_USER_GUIDE.

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

Utilizzare RAG

La generazione con recupero aumentato è uno schema comune per aumentare le risposte del modello con i tuoi dati. È particolarmente utile per grandi quantità di dati, perché funziona indicizzando i dati e recupera solo una piccola parte di dati pertinenti alla query.

Agent Framework offre alcuni modi per integrarsi con diversi sistemi RAG.

Scenari Consigli
Demo / prototipi FilesRetrieval
Quantità ridotta di dati
(una manciata di documenti)		 FilesRetrieval
Soluzione RAG completamente gestita VertexRagRetrieval
Soluzioni RAG fai da te o di altro tipo LlamaIndexRetrieval

FilesRetrieval

FilesRetrieval crea un repository di vettori in memoria all'avvio dell'agente, aggiunge latenza ed è limitato alla memoria e alle prestazioni dell'ambiente di hosting dell'API. Pertanto, questa opzione è adatta solo per demo / prototipi o per la produzione con una quantità molto ridotta di documenti.

FilesRetrieval si basa su LlamaIndex. Devi configurarlo seguendo la documentazione di LlamaIndex.

Una volta configurato, puoi inserire i documenti in una cartella e creare uno strumento di recupero come segue:

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

Vertex RAG Engine è un servizio completamente gestito che gestisce l'importazione, la trasformazione, l'incorporamento, l'indicizzazione e il recupero dei dati.

Per utilizzarlo, segui la guida rapida per configurare il corpus e importare i documenti. Aggiungi lo strumento all'agente.

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

Utilizzando la Ricerca Google, l'agente potrà accedere a informazioni reali in tempo reale e utilizzare la Ricerca Google per effettuare ricerche.

Note

  • L'utilizzo di Grounding con la Ricerca Google può comportare costi aggiuntivi.
  • Per Gemini 1.5:
    • Quando aggiungi lo strumento Ricerca Google a un agente, non puoi avere altri strumenti per quell'agente.
    • Lo strumento di ricerca Google viene sempre eseguito, indipendentemente dal fatto che la query abbia bisogno o meno della Ricerca Google.
  • Per Gemini 2.0 e versioni successive:
    • Puoi utilizzare altri strumenti mentre utilizzi lo strumento Ricerca Google.
    • Lo strumento di ricerca Google viene eseguito solo quando il modello ritiene che sia necessario.
  • I modelli di terze parti non supportano gli strumenti della Ricerca Google.
  • Per utilizzare lo strumento Ricerca Google, devi seguire le linee guida riportate nella pagina Utilizzare i suggerimenti della Ricerca Google, inclusa la visualizzazione sempre di un banner per mostrare le query correlate della Ricerca Google. Anche la nostra UI per gli sviluppatori segue queste regole.

Esempio

Attivare lo strumento Ricerca Google è molto semplice: basta aggiungere google_search all'elenco degli strumenti.

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

Tutorial: valutare il rendimento dell'agente

Valutare l'agente è fondamentale per assicurarti che funzioni come previsto e soddisfi i tuoi standard di qualità. Agent Framework offre diversi modi per valutare il rendimento dell'agente utilizzando file di test e criteri di valutazione.

Come funziona la valutazione

Ogni file di test contiene un elenco di query, traiettorie degli strumenti previste e risposte di riferimento. I file di test possono essere organizzati in cartelle. Se vuoi, una cartella può includere un file test_config.json che specifica i criteri di valutazione.

File di test di esempio

Un file di test contiene una sessione con query, utilizzo previsto dello strumento e risposte di riferimento. Ecco un esempio:

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

Criteri di valutazione

I criteri di valutazione in test_config.json definiscono come verrà misurato il rendimento dell'agente:

  • tool_trajectory_avg_score: valuta le traiettorie degli strumenti.
  • response_match_score: valuta le risposte.

Se non vengono forniti criteri di valutazione, verrà applicata una configurazione predefinita.

Esempi di criteri di valutazione (test_config.json)

Ecco un esempio di file test_config.json che specifica i criteri di valutazione personalizzata:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
  • tool_trajectory_avg_score: impostato su 1,0, il che significa che è previsto un utilizzo perfetto della traiettoria dello strumento.
  • response_match_score: impostato su 0,8, consente un piccolo margine di errore nelle risposte dell'agente.

Modalità di esecuzione della valutazione

1. af web - Esegui valutazioni tramite l'interfaccia utente web

Puoi valutare gli agenti in modo interattivo utilizzando la nostra UI basata sul web.

Passaggi:
  1. Avvia il server web eseguendo: bash af web
  2. Nell'interfaccia web:
    • Seleziona un agente.
    • Fai clic su "Salva sessione come file di test" per salvare una sessione come file di test.
    • Fai clic su "Esegui file di test" per visualizzare un popup con i file di test nella cartella dell'agente.
File di test:

I file di test vengono archiviati nella stessa cartella dell'agente. Puoi aggiornare manualmente o aggiungere file di test in base alle tue esigenze.

2. af test - Esegui test tramite riga di comando

Puoi eseguire tutti i file di test in una cartella specificata utilizzando il comando af test. La cartella deve contenere i file di test e la definizione dell'agente.

Esempio:
af test samples/agent_folder

Questo comando individua ed esegue tutti i file di test (*.test.json) nella cartella specificata.

3. pytest - Esegui test in modo programmatico

Puoi anche utilizzare pytest per eseguire file di test nell'ambito dei test di integrazione.

Comando di esempio:
pytest tests/integrations/
Esempio di codice di test:

Ecco un esempio di test case pytest che esegue un singolo file di test:

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

Questo approccio ti consente di integrare le valutazioni degli agenti nelle pipeline CI/CD o in suite di test più grandi.