Create Tools: First Agent SDK Guide

Creating the tools

A tool is a function that an agent can use to carry out actions like calling external APIs or looking up information in a data source, as part of following the instructions defined in the prompt. We’ll need two tools: one to give it access to our data source with the general weather information, and one to give the weather agent the ability to query the Open-Meteo API for real-time weather data. We’ll create the former first.

Python
TypeScript

Before we create the tools, we need to create a service to which we can link them. You can use the sample code below.

from syllable_sdk import SyllableSDK
from syllable_sdk.models import ServiceCreateRequest

sdk = SyllableSDK(
api_key_header='your_key_here'
)

service = sdk.services.create(request=ServiceCreateRequest(
name='Tutorial Weather Service',
description='Service for weather information'
))

print(service)

Before we create the tools, we need to create a service to which we can link them. You can use the sample code below.

import { SyllableSDK } from 'syllable-sdk';

const syllableSDK = new SyllableSDK({
apiKeyHeader: 'yourkeyhere',
});

const service = await syllableSDK.services.create({
name: 'Tutorial Weather Service',
description: 'Service for weather information'
});
console.log(service);

Note the ID of your service. Now we’ll create a tool to access the data source.

Python
TypeScript

from syllable_sdk import SyllableSDK
from syllable_sdk.models import InternalTool, StaticToolParameter, StaticToolParameterType, ToolArgumentLocation, ToolCreateRequest, ToolDefinition, ToolFunction, ToolHTTPEndpoint, ToolHTTPMethod, Type

sdk = SyllableSDK(
api_key_header='your_key_here'
)

general_weather_info_tool = sdk.tools.create(request=ToolCreateRequest(
# The name of the tool is used to reference it elsewhere in the system,
# including in prompts and agents, so you should pick something that's easily
# identifiable. It shouldn't contain any whitespace.
name='tutorial_general_weather_information',
# Enter your service ID here so the tool is added to the service.
service_id=your_service_id_here,
definition=ToolDefinition(
type=Type.ENDPOINT,
endpoint=ToolHTTPEndpoint(
  url='http://helix-app/v1/search',
  method=ToolHTTPMethod.POST,
  argument_location=ToolArgumentLocation.BODY
),
tool=InternalTool(
  type='function',
  function=ToolFunction(
    name='tutorial_general_weather_information',
    description='Look up general weather information from data sources. Returns an answer and a reference URL. Do not include the reference URL in the spoken response.',
    parameters={
      'type': 'object',
      'required': [
        'question'
      ],
      'properties': {
        'question': {
          'type': 'string',
          'description': 'A user inquiry about content in the agent\'s documents, e.g., What are the causes of wind?'
        }
      }
    }
  )
),
static_parameters=[
  StaticToolParameter(
    name='doc',
    description='Data sources to which the tool should have access.',
    required=True,
    type=StaticToolParameterType.DATA_SOURCE_LIST,
    default=[
      'tutorial_weather_facts'
    ]
  )
]
)
))

print(general_weather_info_tool)

import { SyllableSDK } from 'syllable-sdk';
import { StaticToolParameterType, ToolArgumentLocation, ToolHttpMethod, Type } from 'syllable-sdk/models/components/index.js';

const syllableSDK = new SyllableSDK({
apiKeyHeader: 'yourkeyhere',
});

const generalWeatherInfoTool = await syllableSDK.tools.create({
// The name of the tool is used to reference it elsewhere in the system,
// including in prompts and agents, so you should pick something that's easily
// identifiable. It shouldn't contain any whitespace.
name: 'tutorial_general_weather_information',
// Enter your service ID here so the tool is added to the service.
serviceId: yourServiceIdHere,
definition: {
type: Type.Endpoint,
endpoint: {
  url: 'http://helix-app/v1/search',
  method: ToolHttpMethod.Post,
  argumentLocation: ToolArgumentLocation.Body
},
tool: {
  type: 'function',
  function: {
    name: 'tutorial_general_weather_information',
    description: 'Look up general weather information from data sources. Returns an answer and a reference URL. Do not include the reference URL in the spoken response.',
    parameters: {
      type: 'object',
      required: [
        'question'
      ],
      properties: {
        question: {
          type: 'string',
          description: 'A user inquiry about content in the agent\'s documents, e.g., What are the causes of wind?'
        }
      }
    }
  }
},
staticParameters: [
{
    name: 'doc',
    description: 'Data sources to which the tool should have access',
    required: true,
    type: StaticToolParameterType.DataSourceList,
    default: [
      'tutorial_weather_facts'
    ]
  }
]
}
});

console.log(generalWeatherInfoTool);

This tool will query Helix, Syllable’s document management and search service, for an answer to the user’s question, using the tutorial_weather_facts data source that we created as its knowledge base.

The “endpoint” object gives the agent details on what API endpoint to call and how to pass the parameters (in the body of a POST request).
The “tool” object includes a description of the tool, which should be written as instructions to the agent regarding what the tool does. It also includes a “parameters” object, which describes the various parameters that the agent should gather from the user’s input and send to the API endpoint in the “endpoint” object.
The “static parameters” object also describes parameters that should be sent to the API, but are predetermined at configuration time, rather than gathered by the agent from the user’s input.

Now we’ll create our second tool, to call the Open-Meteo API.

Python
TypeScript

from syllable_sdk import SyllableSDK
from syllable_sdk.models import InternalTool, SyllableSDK, ToolArgumentLocation, ToolCreateRequest, ToolDefinition, ToolFunction, ToolHTTPEndpoint, ToolHTTPMethod, Type

sdk = SyllableSDK(
  api_key_header='your_key_here'
)

real_time_weather_tool = sdk.tools.create(request=ToolCreateRequest(
  name='tutorial_get_weather',
  service_id=your_service_id_here,
  definition=ToolDefinition(
    type=Type.ENDPOINT,
    endpoint=ToolHTTPEndpoint(
      url='https://api.open-meteo.com/v1/forecast',
      method=ToolHTTPMethod.GET,
      argument_location=ToolArgumentLocation.QUERY
    ),
    tool=InternalTool(
      type='function',
      function=ToolFunction(
        name='tutorial_get_weather',
        description='Get the weather for a city',
        parameters={
          'type': 'object',
          'properties': {
            'longitude': {
              'type': 'number',
              'description': 'The longitude of the city'
            },
            'latitude': {
              'type': 'number',
              'description': 'The latitude of the city'
            },
            'current': {
              'type': 'string',
              'description': 'information to retrieve from the open-meteo API, comma-separated',
              'default': 'temperature_2m,relative_humidity_2m,precipitation,rain,showers,snowfall'
            }
          },
          'required': [
            'longitude',
            'latitude'
          ]
        }
      )
    ),
    static_parameters=[
      StaticToolParameter(
        name='current',
        description='Information to retrieve from the Open-Meteo API, comma-separated.',
        required=True,
        type=StaticToolParameterType.STRING,
        default='temperature_2m,relative_humidity_2m,precipitation,rain,showers,snowfall'
      )
    ]
  )
))

print(real_time_weather_tool)

import { SyllableSDK } from 'syllable-sdk';
import { ToolArgumentLocation, ToolHttpMethod, Type } from 'syllable-sdk/models/components/index.js';

const syllableSDK = new SyllableSDK({
  apiKeyHeader: 'yourkeyhere',
});

const realTimeWeatherTool = await syllableSDK.tools.create({
  name: 'tutorial_get_weather',
  serviceId: yourServiceIdHere,
  definition: {
    type: Type.Endpoint,
    endpoint: {
      url: 'https://api.open-meteo.com/v1/forecast',
      method: ToolHttpMethod.Get,
      argumentLocation: ToolArgumentLocation.Query
    },
    tool: {
      type: 'function',
      function: {
        name: 'tutorial_get_weather',
        description: 'Get the weather for a city',
        parameters: {
          type: 'object',
          properties: {
            longitude: {
              type: 'number',
              description: 'The longitude of the city'
            },
            latitude: {
              type: 'number',
              description: 'The latitude of the city'
            }
          },
          required: [
            'longitude',
            'latitude'
          ]
        }
      }
    },
    staticParameters: [
      {
        name: 'current',
        description: 'Information to retrieve from the Open-Meteo API, comma-separated',
        required: true,
        type: StaticToolParameterType.String,
        default: 'temperature_2m,relative_humidity_2m,precipitation,rain,showers,snowfall'
      }
    ]
  }
});

console.log(realTimeWeatherTool);

Updating prompt to access tools

Now that we have our two tools, we can make them available to the prompt that we created earlier, so that any agents using that prompt will have access to the tools. We can use the prompts update function to accomplish this.

Python
TypeScript

from syllable_sdk import PromptLlmConfig, PromptLlmProvider, PromptUpdateRequest, SyllableSDK

sdk = SyllableSDK(api_key_header='your_key_here')

updated_prompt = sdk.prompts.update(
  request=PromptUpdateRequest(
    # If you lost the ID of the prompt you created earlier, you can use the
    # prompts.list function to find it.
    id=your_prompt_id_here,
    name='Tutorial Weather Prompt',
    description='Prompt for a weather agent',
    type='prompt_v1',
    # Update the prompt text to include instructions for when to call the two new
    # tools...
    context="""You are a weather agent. You can tell the user information about the current weather in a given city, and also answer general weather-related questions.

When asked about information for a city, call "tutorial_get_weather" with the city information (longitude and latitude). You will reply with the current temperature and relative humidity level based on the response. Using the information on the response, also tell the caller the weather conditions in one simple sentence, like "sunny," or "rainy." If you can't determine the city coordinates with the information given, ask for more information.

When asked a general weather-related question, call "tutorial_general_weather_information" with the question that the user asked you.

When asked about any other topic, don't answer and instead remind the caller that you are a weather agent. Keep the tone professional, friendly, and clear. You are chatting with a user, so always respond naturally and conversationally. Do not use non-verbal cues, describe system actions, or add any other information.""",
    # ...and add the tools to the prompt's tools list.
    tools=['tutorial_general_weather_information', 'tutorial_get_weather'],
    llm_config=PromptLlmConfig(
      provider=PromptLlmProvider.OPENAI, model='gpt-4o', version='2024-08-06', api_version=None
    ),
    include_default_tools=False,
  )
)

print(updated_prompt)

import { SyllableSDK } from 'syllable-sdk';
import { PromptLlmProvider } from 'syllable-sdk/models/components/index.js';

const syllableSDK = new SyllableSDK({
  apiKeyHeader: 'yourkeyhere',
});

const updatedPrompt = await syllableSDK.prompts.update({
  // If you lost the ID of the prompt you created earlier, you can use the
  // prompts.list function to find it.
  id: yourPromptIdHere,
  name: 'Tutorial Weather Prompt',
  description: 'Prompt for a weather agent',
  type: 'prompt_v1',
  // Update the prompt text to include instructions for when to call the two new
  // tools...
  context: `You are a weather agent. You can tell the user information about the current weather in a given city, and also answer general weather-related questions.

When asked about information for a city, call "tutorial_get_weather" with the city information (longitude and latitude). You will reply with the current temperature and relative humidity level based on the response. Using the information on the response, also tell the caller the weather conditions in one simple sentence, like "sunny," or "rainy." If you can't determine the city coordinates with the information given, ask for more information.

When asked a general weather-related question, call "tutorial_general_weather_information" with the question that the user asked you.

When asked about any other topic, don't answer and instead remind the caller that you are a weather agent. Keep the tone professional, friendly, and clear. You are chatting with a user, so always respond naturally and conversationally. Do not use non-verbal cues, describe system actions, or add any other information.`,
  // ...and add the tools to the prompt's tools list.
  tools: [
    'tutorial_general_weather_information',
    'tutorial_get_weather'
  ],
  llmConfig: {
    provider: PromptLlmProvider.OPENAI,
    model: 'gpt-4o',
    version: '2024-08-06',
    apiVersion: null
  },
  includeDefaultTools: false
});

console.log(updatedPrompt);

We have one more step before we’re able to create the agent, and that’s to add a greeting message for the agent to deliver to the user at the beginning of a conversation. Click “Create a message” below to continue the tutorial.

Introduction

Create tools

Creating the tools

Updating prompt to access tools

📚 Documentation References

​Creating the tools

​Updating prompt to access tools

​📚 Documentation References

Creating the tools

Updating prompt to access tools

📚 Documentation References