Tools / Function Calling

class WeatherAPI {
  // we can use literals to denote the name of the tool
  // the field can be named anything we want! "api_name" "tool" "function_name"
  // whatever you feel the LLM would understand best
  api_name "weather_request"
  city string @description("the user's city")
  timeOfDay string @description("As an ISO8601 timestamp")
}

function UseTool(user_message: string) -> WeatherAPI {
  client "openai/gpt-5-mini"
  prompt #"
    Given a message, extract info.
    {# special macro to print the functions return type. #}
    {{ ctx.output_format }}

    {{ _.role('user') }}
    {{ user_message }}
  "#
}

```typescript TypeScript
import { b } from './baml_client'
import { WeatherAPI } from './baml_client/types'
import assert from 'assert'

const main = async () => {
  const weatherInfo = await b.UseTool("What's the weather like in San Francisco?")
  console.log(weatherInfo)
  // BAML doesn't generate concrete types in TypeScript
  // so we can only validate the interfaces
  assert("city" in weatherInfo)
  console.log(`City: ${weatherInfo.city}`)
  console.log(`Time of Day: ${weatherInfo.timeOfDay}`)
}

package main

import (
    "context"
    "fmt"
    
    b "example.com/myproject/baml_client"
    "example.com/myproject/baml_client/types"
)

func getWeather(city string, timeOfDay string) {
    // Your weather API implementation
}

func main() {
    ctx := context.Background()
    
    weatherInfo, err := b.UseTool(ctx, "What's the weather like in San Francisco?")
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("%+v\n", weatherInfo)
    fmt.Printf("City: %s\n", weatherInfo.City)
    fmt.Printf("Time of Day: %s\n", weatherInfo.TimeOfDay)
    
    getWeather(weatherInfo.City, weatherInfo.TimeOfDay)
}

require_relative "baml_client/client"

$b = Baml.Client

def main
  weather_info = $b.UseTool(user_message: "What's the weather like in San Francisco?")
  puts weather_info
  raise unless weather_info.is_a?(Baml::Types::WeatherAPI)
  puts "City: #{weather_info.city}"
  puts "Time of Day: #{weather_info.timeOfDay}"
end

function UseTool(user_message: string) -> WeatherAPI | MyOtherAPI {
  .... // same thing
}

if isinstance(tool, WeatherAPI):
    print(f"Weather API called:")
    print(f"City: {tool.city}")
    print(f"Time of Day: {tool.timeOfDay}")
elif isinstance(tool, MyOtherAPI):
    print(f"MyOtherAPI called:")
    # Handle MyOtherAPI specific attributes here

```typescript TypeScript
import { b } from './baml_client'
import { WeatherAPI, MyOtherAPI } from './baml_client/types'

const main = async () => {
  const tool = await b.UseTool("What's the weather like in San Francisco?")
  console.log(tool)
  
  // BAML doesn't generate concrete types in TypeScript
  // We check which tool by checking if certain fields exist
  if ("city" in tool) {
    console.log("Weather API called:")
    console.log(`City: ${tool.city}`)
    console.log(`Time of Day: ${tool.timeOfDay}`)
  } else if ("operation" in tool) {
    console.log("MyOtherAPI called:")
    // Handle MyOtherAPI specific attributes here
  }

  /*
   * Alternatively, we could modify our BAML file as such
   * 
   * class WeatherAPI {
   *   class_name "WeatherAPI"
   *   city string
   *   time string @description("Current time in ISO8601 format")
   * }
   *
   * class MyOtherAPI {
   *   class_name "MyOtherAPI"
   *   operation "add" | "subtract" | "multiply" | "divide"
   *   numbers float[]
   * }
   *
   * Then, in typescript, we could check the class_name to determine which tool to call
   * 
   * if (tool.class_name === "WeatherAPI") {
   *   // Handle WeatherAPI specific attributes here
   * } else if (tool.class_name === "MyOtherAPI") {
   *   // Handle MyOtherAPI specific attributes here
   * }
   */
}

main()

package main

import (
    "context"
    "fmt"
    
    b "example.com/myproject/baml_client"
    "example.com/myproject/baml_client/types"
)

func main() {
    ctx := context.Background()
    
    tool, err := b.UseTool(ctx, "What's the weather like in San Francisco?")
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("%+v\n", tool)
    
    // Go generates As{TypeName}() methods for union types
    // Method names correspond to the actual union variant names
    if weatherAPI := tool.AsWeatherAPI(); weatherAPI != nil {
        fmt.Println("Weather API called:")
        fmt.Printf("City: %s\n", weatherAPI.City)
        fmt.Printf("Time of Day: %s\n", weatherAPI.TimeOfDay)
    } else if otherAPI := tool.AsMyOtherAPI(); otherAPI != nil {
        fmt.Println("MyOtherAPI called:")
        // Handle MyOtherAPI specific attributes here
    } else {
        fmt.Println("Unknown tool type")
    }
}

require_relative "baml_client/client"

$b = Baml.Client

def main
  tool = $b.UseTool(user_message: "What's the weather like in San Francisco?")
  puts tool
  
  case tool
  when Baml::Types::WeatherAPI
    puts "Weather API called:"
    puts "City: #{tool.city}"
    puts "Time of Day: #{tool.timeOfDay}"
  when Baml::Types::MyOtherAPI
    puts "MyOtherAPI called:"
    # Handle MyOtherAPI specific attributes here
  end
end

main

function UseTool(user_message: string) -> (WeatherAPI | MyOtherAPI)[] {
  client "openai/gpt-5-mini"
  prompt #"
    Given a message, extract info.
    {# special macro to print the functions return type. #}
    {{ ctx.output_format }}

    {{ _.role('user') }}
    {{ user_message }}
  "#
}

for tool in tools:
    if isinstance(tool, WeatherAPI):
        print(f"Weather API called:")
        print(f"City: {tool.city}")
        print(f"Time of Day: {tool.timeOfDay}")
    elif isinstance(tool, MyOtherAPI):
        print(f"MyOtherAPI called:")
        # Handle MyOtherAPI specific attributes here

```typescript TypeScript
import { b } from './baml_client'
import { WeatherAPI, MyOtherAPI } from './baml_client/types'

const main = async () => {
  const tools = await b.UseTool("What's the weather like in San Francisco and New York?")
  console.log(tools)
  
  tools.forEach(tool => {
    if ("city" in tool) {
      console.log("Weather API called:")
      console.log(`City: ${tool.city}`)
      console.log(`Time of Day: ${tool.timeOfDay}`)
    } else if ("operation" in tool) {
      console.log("MyOtherAPI called:")
      // Handle MyOtherAPI specific attributes here
    }
  })
}

main()

package main

import (
    "context"
    "fmt"
    
    b "example.com/myproject/baml_client"
    "example.com/myproject/baml_client/types"
)

func main() {
    ctx := context.Background()
    
    tools, err := b.UseTool(ctx, "What's the weather like in San Francisco and New York?")
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("%+v\n", tools)
    
    for _, tool := range tools {
        if weatherAPI := tool.AsWeatherAPI(); weatherAPI != nil {
            fmt.Println("Weather API called:")
            fmt.Printf("City: %s\n", weatherAPI.City)
            fmt.Printf("Time of Day: %s\n", weatherAPI.TimeOfDay)
        } else if otherAPI := tool.AsMyOtherAPI(); otherAPI != nil {
            fmt.Println("MyOtherAPI called:")
            // Handle MyOtherAPI specific attributes here
        } else {
            fmt.Println("Unknown tool type")
        }
    }
}

require_relative "baml_client/client"

$b = Baml.Client

def main
  tools = $b.UseTool(user_message: "What's the weather like in San Francisco and New York?")
  puts tools
  
  tools.each do |tool|
    case tool
    when Baml::Types::WeatherAPI
      puts "Weather API called:"
      puts "City: #{tool.city}"
      puts "Time of Day: #{tool.timeOfDay}"
    when Baml::Types::MyOtherAPI
      puts "MyOtherAPI called:"
      # Handle MyOtherAPI specific attributes here
    end
  end
end

main

class GetWeather {
  tool_name "get_weather" @description("Use this tool to get the current weather forecast for a specific city.")
  city string @description("The city for which to get the weather.")
}

class GetTimezone {
  tool_name "get_timezone" @description("Use this tool to find the current timezone of a specific city.")
  city string @description("The city for which to find the timezone.")
}

function ChooseTool(query: string) -> GetWeather | GetTimezone {
  client "openai/gpt-5"
  prompt #"
    Given the user query, determine the primary intent and select the appropriate tool to call.

    {# special macro to add tool structures + descriptions here #}
    {{ ctx.output_format }} 

    {{ _.role('user') }}
    {{ query }}
  "#
}

class WeatherAPI {
  @@dynamic // params defined from code
}

function UseTool(user_message: string) -> WeatherAPI {
  client "openai/gpt-5-mini"
  prompt #"
    Given a message, extract info.
    {# special macro to print the functions return type. #}
    {{ ctx.output_format }}

    {{ _.role('user') }}
    {{ user_message }}
  "#
}

</CodeGroup>

<Warning>Note that the above approach is not fully generic. Recommended you read: [Dynamic JSON Schema](https://www.boundaryml.com/blog/dynamic-json-schemas)</Warning>

## Function-calling APIs vs Prompting
Injecting your function schemas into the prompt, as BAML does, outperforms function-calling across all benchmarks for major providers ([see our Berkeley FC Benchmark results with BAML](https://www.boundaryml.com/blog/sota-function-calling?q=0)).

Amongst other limitations, function-calling APIs will at times:
1. Return a schema when you don't want any (you want an error)
2. Not work for tools with more than 100 parameters.
3. Use [many more tokens than prompting](https://www.boundaryml.com/blog/type-definition-prompting-baml).

Keep in mind that "JSON mode" is nearly the same thing as "prompting", but it enforces the LLM response is ONLY a JSON blob.
BAML does not use JSON mode since it allows developers to use better prompting techniques like chain-of-thought, to allow the LLM to express its reasoning before printing out the actual schema. BAML's parser can find the json schema(s) out of free-form text for you. Read more about different approaches to structured generation [here](https://www.boundaryml.com/blog/schema-aligned-parsing)

BAML will still support native function-calling APIs in the future (please let us know more about your use-case so we can prioritize accordingly)


## Create an Agent that utilizes these Tools 

We can create an Agent or an "agentic loop" that continuously uses tools in a program simply by adding a while loop in our code. 
In this example, we'll have two tools:
1. An API that queries the weather.
2. An API that does basic calculations on numbers. 

This is what it looks in the BAML file:

``` Rust tools.baml
class WeatherAPI {
  intent "weather_request"
  city string
  time string @description("Current time in ISO8601 format")
}

class CalculatorAPI {
  intent "basic_calculator"
  operation "add" | "subtract" | "multiply" | "divide"
  numbers float[]
}

function SelectTool(message: string) -> WeatherAPI | CalculatorAPI {
  client "openai/gpt-5"
  prompt #"
    Given a message, extract info.

    {{ ctx.output_format }}

    {{ _.role("user") }} {{ message }}
  "#
}

while True:
    # Get user input
    user_input = input("You: ")
    if user_input.lower() == 'exit':
        break

    # Call the BAML function to select tool
    tool_response = b.SelectTool(user_input)

    # Handle the tool response
    if isinstance(tool_response, WeatherAPI):
        result = handle_weather(tool_response)
        print(f"Agent (Weather): {result}")
    
    elif isinstance(tool_response, CalculatorAPI):
        result = handle_calculator(tool_response)
        print(f"Agent (Calculator): {result}")

```typescript toolAgent.ts
import { b } from "@/baml_client";
import { WeatherAPI, CalculatorAPI } from "@/baml_client/types";

function handleWeather(weather: WeatherAPI): string {
  // Simulate weather API call
  return `The weather in ${weather.city} at ${weather.time} is sunny.`;
}

function handleCalculator(calc: CalculatorAPI): string {
  const numbers = calc.numbers;
  let result: number;

  switch (calc.operation) {
    case "add":
      result = numbers.reduce((a, b) => a + b, 0);
      break;
    case "subtract":
      result = numbers.slice(1).reduce((a, b) => a - b, numbers[0]);
      break;
    case "multiply":
      result = numbers.reduce((a, b) => a * b, 1);
      break;
    case "divide":
      result = numbers.slice(1).reduce((a, b) => a / b, numbers[0]);
      break;
    default:
      return "Unknown operation.";
  }

  return `The result is ${result}`;
}

async function main() {
  console.log("Agent started! Type 'exit' to quit.");

  const readline = await import("readline");

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  rl.on("line", async (input) => {
    if (input.toLowerCase() === "exit") {
      rl.close();
      return;
    }

    const toolResponse = await b.SelectTool(input);

    switch (toolResponse.intent) {
      case "weather_request":
        const weatherResult = handleWeather(toolResponse);
        console.log(`Agent (Weather): ${weatherResult}`);
        break;
      case "basic_calculator":
        const calcResult = handleCalculator(toolResponse);
        console.log(`Agent (Calculator): ${calcResult}`);
        break;
    }
  });
}

main();

package main

import (
    "bufio"
    "context"
    "fmt"
    "os"
    "strings"
    
    b "example.com/myproject/baml_client"
    "example.com/myproject/baml_client/types"
)

func handleWeather(weather *types.WeatherAPI) string {
    // Simulate weather API call
    return fmt.Sprintf("The weather in %s at %s is sunny.", weather.City, weather.Time)
}

func handleCalculator(calc *types.CalculatorAPI) string {
    numbers := calc.Numbers
    var result float64
    
    switch calc.Operation {
    case "add":
        result = 0
        for _, n := range numbers {
            result += n
        }
    case "subtract":
        if len(numbers) > 0 {
            result = numbers[0]
            for _, n := range numbers[1:] {
                result -= n
            }
        }
    case "multiply":
        result = 1
        for _, n := range numbers {
            result *= n
        }
    case "divide":
        if len(numbers) > 0 {
            result = numbers[0]
            for _, n := range numbers[1:] {
                if n != 0 {
                    result /= n
                }
            }
        }
    default:
        return "Unknown operation."
    }
    
    return fmt.Sprintf("The result is %.2f", result)
}

func main() {
    ctx := context.Background()
    fmt.Println("Agent started! Type 'exit' to quit.")
    
    scanner := bufio.NewScanner(os.Stdin)
    
    for {
        fmt.Print("You: ")
        if !scanner.Scan() {
            break
        }
        
        input := scanner.Text()
        if strings.ToLower(input) == "exit" {
            break
        }
        
        // Call the BAML function to select tool
        toolResponse, err := b.SelectTool(ctx, input)
        if err != nil {
            fmt.Printf("Error: %v\n", err)
            continue
        }
        
        // Handle the tool response using generated As methods
        if weatherAPI := toolResponse.AsWeatherAPI(); weatherAPI != nil {
            result := handleWeather(weatherAPI)
            fmt.Printf("Agent (Weather): %s\n", result)
        } else if calcAPI := toolResponse.AsCalculatorAPI(); calcAPI != nil {
            result := handleCalculator(calcAPI)
            fmt.Printf("Agent (Calculator): %s\n", result)
        } else {
            fmt.Println("Agent: Sorry, I couldn't handle that input.")
        }
    }
}

Agent started! Type 'exit' to quit.
You: What's the weather in Seattle
Agent (Weather): The weather in Seattle at 2023-10-02T12:00:00Z is sunny.
You: What's 5+2
Agent (Calculator): The result is 7.0