Quick code tutorial: Call a tool

You can call a tool with an agent programmatically with the watsonx.ai API and SDKs.

This tutorial demonstrates calling a tool with a foundation model. Work with Python, Node.js, or Curl. This example uses the mistralai/mistral-large foundation model, which supports text generation and tool calling. The model is provided with a tool called add and a message with the question “What is 2 plus 4?“. The response of the model is a message that contains the tool that is called and the method of calling that tool.

alt="" You can complete this tutorial in less than 5 minutes.

Detailed information: Automating tasks with AI agents; Building agent-driven workflows with the chat API; Foundation models that support your use case

Prerequisite

Complete the one-time steps to gather your credentials and other information and prepare your system. See Prerequisite one-time tasks.

Call a tool

Python Node.js Curl

To call a tool with a foundation model:

Add the following code to the example.py file and run the code. Replace {watsonx_ai_url}, {apikey}, and {project_id} with your values.

from ibm_watsonx_ai import APIClient
from ibm_watsonx_ai import Credentials
from ibm_watsonx_ai.foundation_models import ModelInference

credentials = Credentials(
   url = "{watsonx_ai_url}",
   api_key = "{apikey}"
)

client = APIClient(credentials)

params = {
   "time_limit": 1000,
   "max_new_token": 300
}

model_id = "mistralai/mistral-large"
project_id = "{project_id}"
space_id = None # optional
verify = False

model = ModelInference(
model_id=model_id,
api_client=client,
params=params,
project_id=project_id,
space_id=space_id,
verify=verify,
)

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": "number"
                  },
                  "b": {
                        "description": "A number value",
                        "type": "number"
                  }
               },
               "required": [
                  "a",
                  "b"
               ]
            }
      }
   }
]

print(model.chat(messages=messages, tools=tools))

print( json.dumps( result["choices"][0], indent=3 ) )

To call a tool with a foundation model:

Add the following code to the example.js file and run the code. Replace {apikey} and {project_id} with your values.

const { WatsonXAI } = require('@ibm-cloud/watsonx-ai');

process.env.IBM_CREDENTIALS_FILE = './.env'; // Your file with the apikey

const watsonxAIService = WatsonXAI.newInstance({
version: '2024-05-31',
serviceUrl: '{watsonx_ai_url}',
});

const params = {
modelId: 'mistralai/mistral-large',
projectId: '{project_id}',
maxTokens: 100,
};

const messages = [
{
   role: 'user',
   content: [
      {
      type: 'text',
      text: 'What is 2 plus 4?',
      },
   ],
},
];

const 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: 'number',
         },
         b: {
            description: 'A number value',
            type: 'number',
         },
      },
      required: ['a', 'b'],
      },
   },
},
];

try {
watsonxAIService
   .textChat({ messages, tools, ...params })
   .then(async ({ result }) => {
      console.log({ response: result.choices?.[0].message });
   });
} catch (err) {
console.warn(err);
}

To call a tool with a foundation model:

Create a JSON file with the following content. Replace {project_id} with your value.

{
"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",
            "required": [ "a", "b" ],
            "properties" : {
               "a" : { "description" : "A number value", "type" : "number" },
               "b" : { "description" : "A number value", "type" : "number" } }
         }
      }
   }
],
"model_id" : "mistralai/mistral-large",
"project_id" : "{project_id}"
}

Run the following curl request. Replace {token} and {JSON-file} with your values.

curl -X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
"{watsonx_ai_url}/ml/v1/text/chat?version=2024-05-31" \
--data-raw '{
   "model_id": "mistralai/mistral-large",
   "project_id": "{project_id}",
   "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": "number"
                  },
                  "b": {
                        "description": "A number value",
                        "type": "number"
                  }
               },
               "required": [
                  "a",
                  "b"
               ]
            }
      }
   }],
   "tool_choice_option": "auto",
   "max_tokens": 300,
   "time_limit": 1000
}'

Sample JSON response:

{
"id": "chat-a00942a130e84f83bc0090c38c2f419f",
"model_id": "mistralai/mistral-large",
"choices": [
   {
      "index": 0,
      "message": {
      "role": "assistant",
      "tool_calls": [
         {
            "id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
            "type": "function",
            "function": {
            "name": "add",
            "arguments": "{\"a\": 2, \"b\": 4}"
            }
         }
      ]
      },
      "finish_reason": "tool_calls"
   }
]
}

Call a function called add with the arguments {a: 2, b: 4}. The function returns the sum of the two numbers, which is 6. This value must be passed to the model as part of the next message, together with the tool call identifier. The message object might look like the following sample:

[
{
   "role": "user",
   "content": [
      {
      "type": "text",
      "text": "What is 2 plus 4?"
      }
   ]
},
{
   "role": "assistant",
   "tool_calls": [
      {
      "id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
      "type": "function",
      "function": {
         "name": "add",
         "arguments": "{\"a\": 2, \"b\": 4}"
      }
      }
   ]
},
{
   "role": "tool",
   "tool_call_id": "chatcmpl-tool-77cbe4e94d88489383a0c6ed1b644674",
   "content": [
      {
      "type": "text",
      "text": "6"
      }
   ]
}
]

The model responds with a natural language answer that includes the response of the tool call.

Next steps

Try your request against another foundation model by changing the value of the model_id parameter. See List supported models.
Try another quick start coding tutorial.
Try the Build and deploy an agent tutorial.

Quick code tutorial: Call a tool

Prerequisite

Call a tool

Next steps

Learn more