Construire des flux de travail pilotés par des agents avec l'API de chat

Utilisez l'API de chat watsonx.ai avec des modèles de base qui prennent en charge l'appel d'outils pour créer des applications pilotées par des agents.

Autorisations requises
Pour exécuter des invites qui utilisent des outils pour générer des résultats, vous devez disposer du rôle Administrateur ou Éditeur dans un projet.
Informations d'identification requises
Vous devez générer des informations d'identification pour vous authentifier auprès des API d' watsonx.ai. Pour plus d'informations, consultez la section Génération d'un jeton porteur.

Les moyens de se développer

Vous pouvez créer des workflows pilotés par des agents en utilisant ces méthodes de programmation :

Présentation

Les applications agentiques permettent à un modèle de fondation de fonctionner comme un agent qui contrôle le flux d'interaction avec l'utilisateur. Vous définissez les paramètres de l'interaction, y compris les outils que le modèle de base peut utiliser, mais vous permettez au modèle de base de décider de la meilleure étape suivante en fonction de l'état actuel de l'interaction. L'appel d'outil est parfois appelé appel de fonction.

Modèles de fondations soutenus

Lorsque vous construisez un flux de travail agentique, choisissez un modèle de base qui répond aux exigences suivantes :

  • Gestion des tâches liées au chat
  • Prise en charge de l'appel d'outils
  • Peut choisir l'action suivante

Avant de pouvoir utiliser l'API, votre administrateur doit installer un modèle de base qui prend en charge les tâches d' function_calling .

Pour obtenir de manière programmatique une liste des modèles de fondation qui prennent en charge l'appel d'outils à partir de l'API de chat, spécifiez le paramètre " filters=task_function_calling lorsque vous soumettez une demande de méthode " Liste des modèles de fondation disponibles".

curl -X GET \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/foundation_model_specs?version=2024-10-10&filters=task_function_calling'

API REST

Vous pouvez spécifier comment les modèles de fondation choisissent un outil pour générer une réponse dans votre requête API comme suit :

Utiliser un outil spécifique
Vous pouvez spécifier un outil que le modèle de fondation doit utiliser pour générer une réponse avec le paramètre tool_choice dans votre requête API. Examinez l'exemple suivant :
Sélection automatique d'un outil
Le modèle de base peut décider de l'outil à appeler à partir d'une liste d'outils fournis pour générer une réponse lorsque vous spécifiez le paramètre tool_choice_option dans votre demande API. Les différents modèles de fondation gèrent l'appel d'outil de différentes manières. Les exemples suivants illustrent certaines différences :

Pour plus de détails, voir la documentation de référence de l'API watsonx.ai.

Exemple de demande d'appel d'outil spécifiant manuellement un outil

L'exemple suivant définit un outil permettant d'obtenir les conditions météorologiques actuelles. L'exemple soumet les données de l'utilisateur au modèle de la fondation et demande au modèle de n'utiliser que l'outil prédéfini pour répondre à la question.

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/chat?version=2024-10-08' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'
  --data '{
      "model_id": "mistralai/mistral-large",
      "project_id": "4947c695-a374-428c-acca-332c1a1dc9e9",
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "What is the weather like in Boston today?"
            }
          ]
        }
      ],
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "get_current_weather",
            "description": "Get the current weather in a given location.",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "The city and state, for example, San Francisco, CA"
                },
                "unit": {
                  "type": "string",
                  "enum": [
                    "celsius",
                    "fahrenheit"
                  ]
                }
              },
              "required": [
                "location"
              ]
            }
          }
        }
      ],
      "tool_choice": {
        "type:": "function",
        "function": {
          "name": "get_current_weather"
        }
      }
      "max_tokens": 300,
      "time_limit": 1000
      }'

Exemple de demande d'appel d'outils avec mistral-large

L'exemple suivant définit deux outils, une fonction pour l'addition et une fonction pour la multiplication. L'exemple soumet les données de l'utilisateur au modèle de la fondation et laisse le modèle choisir l'outil à utiliser pour répondre à la question.

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/chat?version=2024-10-08' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'
  --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'exemple de sortie montre que le modèle, mistral-large dans ce cas, est capable de choisir le bon outil à utiliser pour la tâche, la fonction " 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"
      }
    ]
  }
}

Exemple de demande d'appel d'outil avec granite-3-2b-instruct

La requête suivante définit deux outils, une fonction pour l'addition et une fonction pour la multiplication, et demande au modèle de fondation granite-3-2b-instruct quel outil utiliser.

Les modèles Granite peuvent mieux appeler les outils lorsque vous fournissez une invite système avec la demande. L'invite système suivante est utilisée :

Vous êtes Granite, développé par IBM. Vous êtes un assistant IA utile qui a accès aux outils suivants. Lorsqu'un outil est nécessaire pour répondre à la requête de l'utilisateur, répondez avec <|tool_call|> suivi d'une liste JSON des outils utilisés. Si un outil n'existe pas dans la liste d'outils fournie, informez l'utilisateur que vous n'êtes pas en mesure de répondre à sa demande.

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/chat?version=2024-10-08' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${TOKEN}'

Le corps de la demande contient l'extrait JSON suivant :

{
  "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
}

Le modèle de fondation granite-3-2b-instruct est capable de choisir l'outil adéquat pour répondre à la requête.

La réponse est la suivante :

{
  "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
  }
}

Python

Voir la classe ModelInference de la bibliothèque watsonx.ai Python.

Pour commencer, consultez les exemples de blocs-notes suivants :

En savoir plus