Puoi fornire codice Python in linea come strumento per il tuo agente, il che offre la flessibilità di estendere le funzionalità dell'agente. Questo codice può accettare input forniti dall'agente e restituire un risultato utilizzato dall'agente nella conversazione. Puoi implementare qualsiasi logica personalizzata, connetterti ad API o database proprietari e garantire risultati deterministici per le attività che richiedono precisione.
Nome e descrizione
Quando crei lo strumento, il nome dello strumento e il nome della funzione principale da chiamare devono essere uguali in snake case.
Le stringhe di documentazione sono una parte fondamentale della definizione di uno strumento Python. La stringa di documentazione della funzione viene utilizzata come descrizione dello strumento, che viene fornita agli agenti che utilizzano lo strumento. Le stringhe di documentazione sono un'estensione dei prompt. Una stringa di documentazione chiara, descrittiva e ben strutturata influenza direttamente la comprensione del modello di ciò che fa lo strumento, quando utilizzarlo e quali argomenti fornire. Questa è la chiave per ottenere una selezione di strumenti affidabile e accurata.
Ambiente
Nel codice dello strumento Python, hai accesso a determinate classi e funzioni che ti aiutano a scrivere il codice. Per saperne di più, consulta il riferimento del runtime Python.
Ad esempio,
l'oggetto context di tipo ToolContext è una variabile disponibile a livello globale
che fornisce uno snapshot dello stato attuale della conversazione.
Non devi importarlo o definirlo come parametro; puoi accedervi direttamente.
Contiene informazioni preziose per l'esecuzione di logica complessa.
Di seguito è riportata una suddivisione delle chiavi disponibili nell'oggetto context:
function_call_id: un ID univoco per la chiamata dello strumento specifica in esecuzione.user_content: un dizionario contenente l'ultimo messaggio dell'utente, inclusi il testo e il ruolo. Questo è uno degli attributi di uso comune.state: un dizionario che rappresenta lo stato della sessione. Puoi utilizzarlo per archiviare e recuperare le variabili che devono persistere in più turni di una conversazione (profilo utente, contenuti del carrello degli acquisti e così via).events: un elenco di tutti gli eventi nella cronologia delle conversazioni fino a questo punto, che ti consente di creare strumenti con una consapevolezza contestuale più complessa.session_id: l'identificatore univoco per l'intera sessione di conversazione.invocation_id: un identificatore univoco per il turno attuale della conversazione.agent_name: il nome dell'agente che esegue lo strumento.
Strumenti Python che chiamano altri strumenti
Quando definisci gli strumenti di codice Python, puoi chiamare esplicitamente altri strumenti definiti nell'applicazione dell'agente.
Ad esempio, se hai uno strumento OpenAPI chiamato crm_service_get_cart_information, puoi chiamarlo con il seguente codice:
# Deterministically call another tool from this tool.
# This syntax for OpenAPI spec tool is:
# tools.<tool_name>_<endpoint_name>({tool_args})
res = tools.crm_service_get_cart_information({})
Esempi di codice
Le sezioni seguenti forniscono esempi.
Recuperare l'ultimo input utente
Questo esempio mostra una funzionalità fondamentale: l'accesso all'ultimo messaggio dell'utente.
Lo strumento esamina l'oggetto context.user_content ed estrae il testo dall'ultimo turno dell'utente.
Questo pattern è essenziale per qualsiasi strumento che deve eseguire un'azione basata direttamente su ciò che l'utente ha appena detto.
from typing import Optional
# Docstrings in tools are important because they are directly
# sent to the model as the description for the tool. You should
# think of docstrings as an extension of prompting. Clear and
# descriptive docstrings will yield higher quality tool
# selection from the model.
def get_last_user_utterance() -> Optional[str]:
"""
Retrieves the most recent message sent by the user from the conversation history.
Returns:
The text of the last user message, or None if no user messages are found.
"""
# The 'context.user_content' contains the last input data
# provided by the user.
# We can filter it to find only the text input from the user.
user_messages = [
part.text for part in context.user_content.parts
if context.user_content.role == "user"
]
if user_messages:
# The most recent message is the first one in the list.
return user_messages[0]
return None
Recuperare e aggiornare le variabili
I modelli linguistici non possono modificare direttamente lo stato della sessione. Questo è intenzionale, in quanto garantisce che le modifiche dello stato vengano gestite in modo controllato e prevedibile. Lo stato può essere modificato solo tramite due meccanismi: strumenti Python o callback.
Questo esempio mostra come uno strumento Python può gestire lo stato.
Lo strumento legge innanzitutto il customer_profile corrente da context.state.
Esegue quindi la logica di business (aggiungendo punti) e riscrive il profilo aggiornato in context.state.
Questo nuovo stato sarà quindi disponibile per l'agente e altri strumenti per il resto della sessione.
from pydantic import BaseModel, Field
from typing import Optional, Dict, Any
# Using Pydantic defines the expected structure of your state variables. This makes your code more reliable and easier to
# debug.
class CustomerProfile(BaseModel):
email: Optional[str] = None
loyalty_points: int = Field(default=0, ge=0) # Must be >= 0
plan: str = "Standard"
# Docstrings in tools are important because they are directly
# sent to the model as the description for the tool. You should
# think of docstrings as an extension of prompting. Clear and
# descriptive docstrings will yield higher quality tool
# selection from the model.
def update_customer_loyalty_points(points_to_add: int) -> Dict[str, Any]:
"""
Adds loyalty points to the customer's profile and returns the updated profile.
Args:
points_to_add: The number of loyalty points to add to the existing total.
Returns:
A dictionary containing the customer's updated profile information.
"""
# 1. Get the current profile data from the session state.
# The .get() method safely returns an empty dict if
# 'customer_profile' doesn't exist.
current_profile_data = context.state.get("customer_profile", {})
# 2. Load the data into a Pydantic model for validation and easy access.
profile = CustomerProfile(**current_profile_data)
# 3. Perform the business logic.
# Print statements can be used for debugging and will show
# up in the tracing details.
profile.loyalty_points += points_to_add
print(f"Updated loyalty points to: {profile.loyalty_points}")
# 4. Save the updated data back into the session state.
# .model_dump() converts the Pydantic model back to a
# dictionary.
context.state["customer_profile"] = profile.model_dump()
return context.state["customer_profile"]
Richieste di rete esterne
Gli strumenti Python possono effettuare richieste di rete esterne, utili per recuperare dati in tempo reale o per l'integrazione con servizi di terze parti che non hanno una specifica OpenAPI. Questo fornisce un'alternativa flessibile all'utilizzo di strumenti basati su OpenAPI. L'esempio utilizza la libreria di richieste standard (disponibile nell'ambiente) per chiamare un'API pubblica e recuperare un fatto casuale.
from typing import Optional
# Docstrings in tools are important because they are directly sent to the model as the
# description for the tool. You should think of docstrings as an extension of prompting.
# Clear and descriptive docstrings will yield higher quality tool selection from the model.
def get_random_fact() -> Optional[str]:
"""
Fetches a random fact from a public API.
Returns:
A string containing the fact on success, or None if an error occurs.
"""
# The 'ces_requests' library is inspired by 'requests', a standard and powerful way in Python
# to make HTTP network calls to any external API, just like you would with `curl` or a web browser.
url = "https://uselessfacts.jsph.pl/api/v2/facts/random"
try:
# This example calls a public API that is completely open and requires no authentication
# (like an API key). Many other APIs for services like weather or e-commerce require you
# to send credentials, often as an API key in the request headers or parameters.
res = ces_requests.get(url=url, json=request_body, headers=headers)
# Example POST request
#res = ces_requests.post(url=url, json=request_body, headers=headers)
# This is a standard practice with 'ces_requests' to check if the call was successful. It will
# raise an error for statuses like 404 or 500.
res.raise_for_status()
fact_data = res.json()
return fact_data.get("text")
except:
return None