Creazione di flussi di lavoro guidati da agenti con l'API di chat
Utilizzate l'API di chat watsonx.ai con i modelli di fondazione che supportano le chiamate agli strumenti per creare applicazioni guidate dagli agenti.
Modi per sviluppare
È possibile creare flussi di lavoro guidati da agenti utilizzando questi metodi di programmazione:
In alternativa, è possibile utilizzare gli strumenti grafici dell'interfaccia utente di watsonx.ai per creare gli agenti. Vedi Agent Lab.
Panoramica
Le applicazioni agenziali consentono a un foundation model di funzionare come un agente che controlla il flusso di interazione con l'utente. Si definiscono i parametri dell'interazione, compresi gli strumenti che il foundation model può utilizzare, ma si consente al foundation model di decidere il passo successivo migliore in base allo stato attuale dell'interazione. Il richiamo di uno strumento è talvolta indicato come richiamo di una funzione.
In un flusso di lavoro reale, si potrebbe voler chiamare sempre uno strumento all'inizio di ogni interazione. Più avanti nello scambio, si potrebbero utilizzare prompt diversi in base al modo in cui l'utente risponde alle domande di follow-up su un'attività. Oppure si potrebbero chiamare vari strumenti di terze parti necessari per completare il flusso di lavoro. È possibile definire queste opzioni e lasciare che sia il foundation model a scegliere il prompt da restituire o lo strumento da utilizzare al momento giusto.
Ad esempio, un'applicazione per la prenotazione di un ristorante potrebbe dover raccogliere le seguenti informazioni e poi creare una prenotazione:
- Ubicazione
- Numero di ospiti
- Data e ora
L'ordine di raccolta delle informazioni può essere importante solo in alcune località, dove il numero di ospiti per tavolo è limitato o dove sono disponibili più posti a sedere all'esterno in caso di bel tempo. È possibile tenere conto di queste condizioni nel codice e lasciare che il foundation model determini quando chiamare strumenti aggiuntivi, come un'applicazione meteo di terze parti, prima che l'agente completi una richiesta di prenotazione.
Modelli di fondazione supportati
Quando si costruisce un flusso di lavoro agenziale, si deve scegliere un foundation model che soddisfi i seguenti requisiti:
- Gestisce le attività di chat
- Supporta la chiamata agli strumenti
- Può scegliere l'azione successiva
Per ottenere programmaticamente un elenco di modelli di fondazione che supportano la chiamata di strumenti dall'API della chat, specificare il parametro 'filters=task_function_calling quando si invia una richiesta del metodo List the available foundation models.
Vedere il riferimento API.
Ad esempio:
curl -X GET \
'https://{region}.ml.cloud.ibm.com/ml/v1/foundation_model_specs?version=2024-10-10&filters=task_function_calling'
Costruire con Python
Vedere la classe Model Inference della libreria watsonx.ai Python.
Esempi di quaderni Python
Sono disponibili i seguenti quaderni campione:
Utilizzate l'API REST per creare una chat che chiami strumenti di terze parti: Utilizzare watsonx e mistral-large per effettuare semplici conversazioni e chiamate a strumenti di chat
Utilizzate l'SDK Python per conversare tra vari tipi di utenti, come il prompt di sistema, l'assistente e l'utente, e quindi chiamare vari strumenti per eseguire equazioni matematiche in base agli input dell'utente. Vedere Utilizzare watsonx e mistral-large per effettuare semplici conversazioni via chat e chiamate con gli strumenti
Utilizzare l'SDK Python per chiamare strumenti che ottengono informazioni da includere in una conversazione, anche utilizzando LangChain per scrivere e implementare funzioni di calcolo e illustrando il flusso di lavoro seguito con LangGraph. Vedere Utilizzare watsonx e mistral-large con il supporto di strumenti per eseguire semplici calcoli.
Dettagli API REST
Per i dettagli sui metodi API, consultare la documentazione di riferimento dell'API.
Esempio di richiesta di chiamata di strumenti
L'esempio seguente definisce due strumenti, una funzione per l'addizione e una per la moltiplicazione. L'esempio invia l'input dell'utente al foundation model e lascia che il modello scelga quale strumento utilizzare per rispondere alla domanda.
Nell'esempio seguente, sostituire la variabile '{url} con il valore giusto per la propria istanza, ad esempio 'us-south.ml.cloud.ibm.com. Aggiungete il vostro token al portatore e l'ID del progetto.
curl -X POST \
'https://{url}/ml/v1/text/chat?version=2024-10-08' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOi...'
--data '{
"model_id": "mistralai/mistral-large",
"project_id": "4947c695-a374-428c-acca-332c1a1dc9e9",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is 2 plus 4?"
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "add",
"description": "Adds the values a and b to get a sum.",
"parameters": {
"type": "object",
"properties": {
"a": {
"description": "A number value",
"type": "float"
},
"b": {
"description": "A number value",
"type": "float"
}
},
"required": [
"a",
"b"
]
}
}
},
{
"type": "function",
"function": {
"name": "multiply",
"description": "Multiplies the values a and b.",
"parameters": {
"type": "object",
"properties": {
"a": {
"description": "A number value",
"type": "float"
},
"b": {
"description": "A number value",
"type": "float"
}
},
"required": [
"a",
"b"
]
}
}
}
],
"tool_choice_option": "auto",
"max_tokens": 300,
"time_limit": 1000
}'
L'output di esempio mostra che il modello, in questo caso mistral-large, è in grado di scegliere lo strumento corretto da utilizzare per il compito, la funzione 'add.
{
"id": "chatcmpl-2f47da4026950db321698cb733b25e89",
"model_id": "mistralai/mistral-large",
"model": "mistralai/mistral-large",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"tool_calls": [
{
"id": "H6KoCbaZV",
"type": "function",
"function": {
"name": "add",
"arguments": "{\"a\": 2, \"b\": 4}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"created": 1739311926,
"model_version": "2.0.0",
"created_at": "2025-02-11T22:12:07.243Z",
"usage": {
"completion_tokens": 25,
"prompt_tokens": 189,
"total_tokens": 214
},
"system": {
"warnings": [
{
"message": "This model is a Non-IBM Product governed by a third-party license that may impose use restrictions and other obligations. By using this model you agree to its terms as identified in the following URL.",
"id": "disclaimer_warning",
"more_info": "https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html?context=wx"
}
]
}
}
Esempio di richiesta di chiamata di utensili con granite-3-2b-instruct
La richiesta seguente definisce due strumenti, una funzione per l'addizione e una per la moltiplicazione, e chiede al foundation model granite-3-2b-instruct quale strumento utilizzare.
I modelli Granite possono chiamare meglio gli strumenti quando si fornisce un prompt di sistema con la richiesta. Viene utilizzato il seguente prompt di sistema:
You are Granite, sviluppato da IBM. Sei un assistente AI con accesso ai seguenti strumenti. Quando è necessario uno strumento per rispondere alla domanda dell'utente, rispondere con <|tool_call|> seguito da un elenco JSON di strumenti utilizzati. Se uno strumento non è presente nell'elenco di strumenti fornito, informare l'utente che non si è in grado di soddisfare la richiesta.
Nell'esempio seguente, sostituire la variabile '{url} con il valore giusto per la propria istanza, ad esempio 'us-south.ml.cloud.ibm.com. Aggiungete il vostro token al portatore e l'ID del progetto.
curl -X POST \
'https://{url}/ml/v1/text/chat?version=2024-10-08' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOi...'
Il corpo della richiesta contiene il seguente frammento JSON:
{
"model_id": "ibm/granite-3-2b-instruct",
"project_id": "4947c695-a374-428c-acca-332c1a1dc9e9",
"messages": [
{
"role":"system",
"content":[
{
"type":"text",
"text":"You are Granite, developed by IBM. You are a helpful AI assistant with access to the following tools. When a tool is required to answer the user's query, respond with <|tool_call|> followed by a JSON list of tools used. If a tool does not exist in the provided list of tools, notify the user that you do not have the ability to fulfill the request."
}
]
},
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is 2 times 4?"
}
]
}
],
"tools": [
{
"type": "function",
"function": {
"name": "add",
"description": "Adds the values a and b to get a sum.",
"parameters": {
"type": "object",
"properties": {
"a": {
"description": "A number value",
"type": "float"
},
"b": {
"description": "A number value",
"type": "float"
}
},
"required": [
"a",
"b"
]
}
}
},
{
"type": "function",
"function": {
"name": "multiply",
"description": "Multiplies the values a and b.",
"parameters": {
"type": "object",
"properties": {
"a": {
"description": "A number value",
"type": "float"
},
"b": {
"description": "A number value",
"type": "float"
}
},
"required": [
"a",
"b"
]
}
}
}
],
"tool_choice_option": "auto",
"max_tokens": 300,
"time_limit": 10000
}
Il foundation model granite-3-2b-instruct è in grado di scegliere lo strumento corretto per rispondere alla domanda.
La risposta è la seguente:
{
"id": "chatcmpl-ac80d63a85209b48592435687086e1c2",
"model_id": "ibm/granite-3-2b-instruct",
"model": "ibm/granite-3-2b-instruct",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"tool_calls": [
{
"id": "chatcmpl-tool-3297286588a24459b0042943cae55629",
"type": "function",
"function": {
"name": "multiply",
"arguments": "{\"a\": 2, \"b\": 4}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"created": 1739311794,
"model_version": "1.1.0",
"created_at": "2025-02-11T22:09:55.048Z",
"usage": {
"completion_tokens": 28,
"prompt_tokens": 348,
"total_tokens": 376
}
}
Ulteriori informazioni
- Credenziali per l'accesso al programma
- Aggiunta di una funzione di chat generativa alle applicazioni con l'API di chat
- Modelli di fondazione supportati
Argomento principale: Codificare soluzioni di IA generativa