Guida il comportamento dell'agente con il contesto creato

Questa pagina descrive il modo migliore per fornire il contesto creato agli agenti di dati dell'API Analisi conversazionale scrivendo prompt efficaci tramite le istruzioni di sistema e, per alcune origini dati, fornendo anche un contesto strutturato. Anche se la fornitura del contesto creato è facoltativa, un contesto creato ben strutturato può migliorare l'accuratezza e la pertinenza delle risposte fornite dall'API.

Che cos'è il contesto creato?

Il contesto creato è una guida che gli sviluppatori possono fornire per definire il comportamento di un agente di dati e perfezionare le risposte dell'API. Questa guida include istruzioni di sistema in formato libero e, per alcune origini dati, campi di contesto strutturati con informazioni come descrizioni delle tabelle e query di esempio. Per rispondere alle domande, l'agente combina questo contesto creato con le informazioni provenienti dalle origini dati (ad esempio tabelle BigQuery, Looker Explore e origini dati di Looker Studio) e con la cronologia delle conversazioni (per le conversazioni a più turni).

Fornendo indicazioni chiare tramite campi contestuali strutturati e istruzioni di sistema in formato libero, puoi migliorare la capacità dell'agente di interpretare le domande degli utenti e generare risposte utili e accurate. Un contesto ben definito è particolarmente utile se ti connetti a dati come le tabelle BigQuery. Ad esempio, puoi utilizzare il contesto creato per fornire i seguenti tipi di indicazioni a un agente:

Logica specifica per l'attività: definisci un cliente "fedele" come un cliente che ha effettuato più di cinque acquisti in un determinato periodo di tempo.
Formattazione delle risposte: riepiloga tutte le risposte dell'agente di dati in massimo 20 parole per far risparmiare tempo agli utenti.
Presentazione dei dati: formatta tutti i numeri in modo che corrispondano alla guida di stile dell'azienda.

Fornire il contesto creato

Le informazioni specifiche che puoi fornire dipendono dall'origine dati. Per i dati BigQuery e i dati Looker, puoi definire sia il contesto strutturato sia le istruzioni di sistema. Per risultati ottimali, fornisci prima il contesto all'agente tramite i campi strutturati disponibili. Poi puoi fornire indicazioni supplementari definendo le istruzioni di sistema.

Fornisci il contesto strutturato nei campi API per dettagli come le descrizioni delle tabelle e le query di esempio. Fornisci le istruzioni di sistema come stringa in formato YAML utilizzando il parametro system_instruction.

Dopo aver definito il contesto creato, puoi fornirlo all'API in una delle seguenti chiamate:

Creazione di un agente di dati persistente: includi il contesto creato nell'oggetto published_context nel corpo della richiesta per configurare il comportamento dell'agente che persiste in più conversazioni. Per saperne di più, consulta Creare un agente di dati (HTTP) o Configurare il contesto per la chat con stato o senza stato (SDK Python).
Invio di una richiesta senza stato: fornisci il contesto creato all'interno dell'inline_context oggetto in una richiesta di chat per definire il comportamento dell'agente per quella specifica chiamata API. Per saperne di più, consulta Creare una conversazione a più turni senza stato (HTTP) o Inviare una richiesta di chat senza stato con contesto in linea (SDK Python).
Invia una richiesta di dati di query: per le origini dati del database, fornisci l'ID del set di contesto del contesto creato all'interno dell'oggetto agent_context_reference nella richiesta di dati di query. Per saperne di più, consulta Definire il contesto dell'agente di dati per le origini dati del database.

Best practice per la creazione di agenti: utilizzare il controllo della versione per il contesto creato

Utilizza i campi stagingContext, publishedContext e lastPublishedContext per controllare le versioni del contesto durante la creazione di agenti con l'API Analisi conversazionale. Il seguente caso d'uso illustra come utilizzare questi campi per creare una versione di gestione temporanea e di produzione del contesto dell'agente.

Supponiamo che tu utilizzi un agente esistente con il campo publishedContext, ma devi apportare un aggiornamento all'agente (ad esempio, rendere tutti i grafici verdi anziché blu).

Per apportare le modifiche e testarle prima della pubblicazione:

Apporta le modifiche all'agente nel campo stagingContext e testalo con le modifiche.
Quando le modifiche sono pronte, aggiorna il campo publishedContext con le modifiche apportate a stagingContext.
Se necessario, puoi ripristinare il vecchio agente aggiornando publishedContext a lastPublishedContext.