Tool Calling in Flyflow

Flyflow provides a feature called "Tool Calling" that allows agents to invoke external tools or services during a call based on the conversation context. Tools are predefined functions or integrations that can be triggered by the agent to perform specific tasks or retrieve additional information. This feature enables you to extend the capabilities of your agents and create more interactive and dynamic conversations.

Defining Tools for an Agent

To enable tool calling for an agent, you need to define the available tools when creating or updating the agent. Tools are specified as an array of objects in the tools property of the agent configuration.

Each tool object should have the following properties:

• type: The type of the tool, which should be set to "function".
• function: An object that defines the details of the tool function.
  • name: The name of the tool function.
  • description: A brief description of what the tool function does.
  • parameters: An object that defines the input parameters required by the tool function.
    • type: The type of the parameters object, which should be set to "object".
    • properties: An object that defines the individual parameters and their types.
    • required: An array that specifies the required parameters for the tool function.

Here's an example of defining tools for an agent:

{
  "name": "Weather Agent",
  "system_prompt": "You are a helpful weather assistant.",
  "webhook": "https://your-webhook-url.com/tools",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "format": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The temperature unit to use. Infer this from the user's location."
            }
          },
          "required": ["location", "format"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "get_n_day_weather_forecast",
        "description": "Get an N-day weather forecast",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "format": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The temperature unit to use. Infer this from the user's location."
            },
            "num_days": {
              "type": "integer",
              "description": "The number of days to forecast"
            }
          },
          "required": ["location", "format", "num_days"]
        }
      }
    }
  ]
}

In this example, the agent has two tool functions defined: get_current_weather and get_n_day_weather_forecast. Each tool function has a name, description, and a set of input parameters with their types and descriptions.

Additionally, the agent configuration includes a webhook property that specifies the URL where the tool calls will be sent as webhooks.

Handling Tool Calls via Webhooks

When an agent invokes a tool during a call, Flyflow sends a webhook request to the specified webhook URL. The webhook request contains information about the invoked tool function and its input parameters.

Your webhook endpoint should be able to handle these incoming requests, execute the corresponding tool function, and send the result back to Flyflow.

Here's an example of how you can handle tool calls via webhooks in Python using the Flask web framework:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/tools', methods=['POST'])
def handle_tool_call():
    payload = request.get_json()
    tool_name = payload['name']
    tool_arguments = payload['arguments']

    # Execute the tool function based on the tool name
    if tool_name == 'get_current_weather':
        location = tool_arguments['location']
        format = tool_arguments['format']
        # Call the actual function to get the current weather
        result = get_current_weather(location, format)
    elif tool_name == 'get_n_day_weather_forecast':
        location = tool_arguments['location']
        format = tool_arguments['format']
        num_days = tool_arguments['num_days']
        # Call the actual function to get the N-day weather forecast
        result = get_n_day_weather_forecast(location, format, num_days)
    else:
        # Handle unknown tool function
        result = {'error': 'Unknown tool function'}

    # Send the tool result back to Flyflow
    return jsonify(result)

if __name__ == '__main__':
    app.run()

In this example, the /tools endpoint is defined to handle incoming POST requests for tool calls. When a request is received, the tool name and arguments are extracted from the payload.

Based on the tool name, the corresponding tool function is executed with the provided arguments. The actual implementation of the tool functions (get_current_weather and get_n_day_weather_forecast) is not shown here and would need to be defined separately.

The result of the tool function is then sent back to Flyflow as a JSON response.

Handling Tool Results

After the webhook endpoint executes the tool function and sends the result back to Flyflow, the agent can access the tool result and incorporate it into the conversation flow.

Flyflow will include the tool result in the tool_calls array of the agent's response. The agent can process the tool result and use it to provide a relevant response to the user or make further decisions based on the obtained information.

Here's an example of how the agent can access and use the tool result:

def handle_agent_response(response):
    tool_calls = response['tool_calls']
    for tool_call in tool_calls:
        tool_name = tool_call['name']
        tool_result = tool_call['result']

        if tool_name == 'get_current_weather':
            temperature = tool_result['temperature']
            conditions = tool_result['conditions']
            humidity = tool_result['humidity']
            # Use the weather information to generate a response
            response_text = f"The current weather in {tool_call['arguments']['location']} is: Temperature: {temperature}°F, Conditions: {conditions}, Humidity: {humidity}%"
            send_response(response_text)
        elif tool_name == 'get_n_day_weather_forecast':
            forecast = tool_result['forecast']
            # Use the weather forecast information to generate a response
            response_text = f"The {tool_call['arguments']['num_days']}-day weather forecast for {tool_call['arguments']['location']} is:\n"
            for day in forecast:
                response_text += f"- Day {day['day']}: Temperature: {day['temperature']}°F, Conditions: {day['conditions']}\n"
            send_response(response_text)

In this example, the handle_agent_response function receives the agent's response, which includes the tool_calls array. It iterates over the tool calls and extracts the tool name and result.

Based on the tool name, the agent can access the relevant information from the tool result and generate an appropriate response to send back to the user.

Conclusion

Tool calling in Flyflow allows agents to invoke external tools or services during a call based on the conversation context. By defining tool functions for an agent and specifying a webhook URL, you can extend the capabilities of your agents and create more interactive and dynamic conversations.

When an agent invokes a tool, Flyflow sends a webhook request to the specified URL, containing information about the invoked tool function and its input parameters. Your webhook endpoint should handle these requests, execute the corresponding tool function, and send the result back to Flyflow.

The agent can then access the tool result and incorporate it into the conversation flow, providing relevant information or taking further actions based on the obtained data.

By leveraging tool calling and webhooks, you can integrate your agents with various external services, APIs, or databases, enabling them to retrieve additional information, perform actions, or trigger specific workflows based on the user's input and the conversation context.

Tool calling provides a powerful way to enhance the functionality and versatility of your Flyflow-powered conversational agents, creating more engaging and efficient user experiences.