Working with tools
Implement and call tools in your agents that comply with the Agent Connect Framework
Tools are a powerful feature that enable AI agents to invoke external APIs and services, thereby extending their capabilities. This guide outlines the implementation and usage of tools within your agents that follow the Agent Connect Framework specification.
Tools allow agents to:
- Invoke External Services: Access APIs, databases, and other external services.
- Perform Specialized Tasks: Execute tasks requiring specific capabilities.
- Collaborate: Share tool results to work together with other agents.
Within the ACF, both tool and tool responses can be shared among agents. This form of observability allows one agent to leverage the work performed by another agent. For instance, a CRM agent might retrieve account information and store details in a tool call response. Subsequently, an Email agent can utilize this information to find critical details, such as an email address for an account.
By sharing tools and their responses, agents can collaborate on sub-tasks while sharing contextual information essential to the overall success of the main task.
Creating your agent
Before you create your tools, you must first create an agent that will use the tool. The ACF requires at least 2 endpoints to be implemented in your agent:
GET /v1/chat
: The Chat API enables agents to communicate and collaborate with each other using a standard chat completions style protocol with server-sent events (SSE) for streaming responses. This API supports both stateful and stateless agents.POST /v1/agents
: The Agent Discovery endpoint enables the identification of available agents and their capabilities within the Agent Connect Framework (ACF), eliminating the need for hardcoded knowledge of their existence.
You can see examples of implemented agents in the Examples page.
Alternatively, for a better integration with watsonx Orchestrate, you can use the watsonx Orchestrate Agent Development Kit (ADK) to develop your agents and tools. To learn how to create your agent by using the ADK, see Creating agents.
Defining your tools
The ACF assumes tools are defined using a JSON schema that specifies the tool’s name, description, and parameters, following the OpenAI specification for function calling:
Key components
name
: A unique identifier for the tooldescription
: A human-readable description of what the tool doesparameters
: A JSON Schema object that defines the tool’s input parametersproperties
: The parameters the tool acceptsrequired
: Which parameters are required
Certain LLMs and frameworks use a different format for tool definitions, tool calls, and tool responses. ACF requires at least these key components to be present in the tool calls.
You can also use the ADK to create tools that are compatible with watsonx Orchestrate agents. For more information, see Creating Tools.
How to implement tools in your agents
Agent frameworks usually implement their own mechanisms to implement tools.
The watsonx Orchestrate ADK uses Python decorators to implement Python-based tools.
Regardless of the framework that you use, you must implement the tool call in your /v1/chat
endpoint.
The following example shows how you can implement a tool from scratch, and how to modify your /v1/chat
endpoint to run your tools.
First, define the tools that your agent will use. You can use a JSON file, an OpenAPI specification, or even a JSON-like structure in your programming language of choice:
Next, implement the actual functions that will be called when a tool is invoked:
Modify your chat completion endpoint to handle tool calls:
Implement the function to process messages and handle tool calls:
Implement the function to stream responses with tool calls:
Logging
When an agent calls a tool, it can log the tool call in its event stream. The tool call event follows this format:
Tool Responses in Agent Connect
After a tool is executed, the result be returned in this format: