​

Tool Calling

Tool Calling in BRX allows your AI applications to interact with external tools, APIs, and services. This enables BRKs to access real-time data, perform actions in the real world, and integrate with existing systems.

​

What is Tool Calling?

Tool Calling is a mechanism that allows BRKs to:

1. Make API requests to external services
2. Execute code or functions
3. Access databases and other data sources
4. Interact with file systems
5. Trigger workflows in other systems

This capability transforms BRKs from simple prompt templates into powerful applications that can interact with the world.

​

How Tool Calling Works

In BRX, Tool Calling is implemented through special BRKs that are configured to interact with external systems. These BRKs can:

1. Format data for external APIs
2. Make HTTP requests
3. Parse and process responses
4. Handle errors and retries
5. Pass results to other BRKs in the workflow

​

Tool Calling Flow

The typical flow for a Tool Calling operation is:

1. A BRK prepares data for the external tool
2. The BRX engine executes the tool call
3. The external tool processes the request and returns a response
4. The BRX engine parses the response
5. The result is passed back to the BRK or to dependent BRKs

​

Implementing Tool Calling

​

HTTP Requests

The most common form of Tool Calling is making HTTP requests to external APIs. Here’s an example of a BRK that calls a weather API:

const weatherBrk = {
  brxId: 'weather-api-brk',
  brxName: 'Weather API',
  description: 'Gets weather information for a location',
  prompt: {
    prompt: new Map([
      ['main', `
        Make an HTTP request to get weather information for {{location}}.
        
        URL: https://api.weather.com/v1/current?location={{location}}&units=metric
        Method: GET
        Headers: {
          "Authorization": "Bearer {{api_key}}",
          "Content-Type": "application/json"
        }
        
        Parse the response and extract the temperature, conditions, and forecast.
      `]
    ])
  },
  processParams: {
    processType: 0
  },
  dependantBrxIds: new Map([
    ['main_brx_entry_schema', 'weather-api-brk']
  ])
};

​

Function Execution

BRX can also execute custom functions as part of a BRK:

const calculationBrk = {
  brxId: 'calculation-brk',
  brxName: 'Calculation',
  description: 'Performs a complex calculation',
  prompt: {
    prompt: new Map([
      ['main', `
        Execute the following JavaScript function:
        
        function calculate(a, b, c) {
          return (a * b) / c;
        }
        
        Input values:
        a = {{value_a}}
        b = {{value_b}}
        c = {{value_c}}
        
        Return the result of the calculation.
      `]
    ])
  },
  processParams: {
    processType: 0
  },
  dependantBrxIds: new Map([
    ['main_brx_entry_schema', 'calculation-brk']
  ])
};

​

Advanced Tool Calling

​

Authentication

Many external APIs require authentication. BRX supports various authentication methods:

• API Keys
• OAuth tokens
• Basic authentication
• Custom authentication schemes

​

Error Handling

Tool Calling operations can fail for various reasons. BRX provides mechanisms for handling errors:

• Retry logic for transient failures
• Fallback options for unavailable services
• Error reporting and logging

​

Caching

To improve performance and reduce API calls, BRX supports caching of tool call results:

• Time-based caching
• Conditional caching based on input parameters
• Cache invalidation strategies

​

Best Practices

• Rate limiting: Be mindful of API rate limits and implement appropriate throttling
• Error handling: Implement robust error handling for all tool calls
• Security: Securely manage API keys and other credentials
• Validation: Validate inputs before making external calls
• Monitoring: Monitor tool call performance and error rates
• Documentation: Document the external dependencies of your BRKs
• Testing: Test tool calls with mock services before using in production

​

Use Cases

Tool Calling enables a wide range of use cases:

• Data enrichment: Augment BRK inputs with data from external sources
• Real-time information: Access up-to-date information like weather, stock prices, or news
• Integration: Connect BRX workflows with existing systems and services
• Automation: Trigger actions in other systems based on BRK outputs
• Complex calculations: Perform calculations that would be difficult to express in prompts