Tool Calling (Function Calling)

1
from openai import OpenAI
2
3
client = OpenAI(
4
    base_url="https://api.runcaptain.com/v1",
5
    api_key="your_api_key",
6
    default_headers={"X-Organization-ID": "your_org_id"}
7
)
8
9
# Define a tool
10
tools = [{
11
    "type": "function",
12
    "function": {
13
        "name": "get_weather",
14
        "description": "Get current weather for a location",
15
        "parameters": {
16
            "type": "object",
17
            "properties": {
18
                "location": {
19
                    "type": "string",
20
                    "description": "City name, e.g. San Francisco"
21
                },
22
                "unit": {
23
                    "type": "string",
24
                    "enum": ["celsius", "fahrenheit"]
25
                }
26
            },
27
            "required": ["location"]
28
        },
29
        "strict": True
30
    }
31
}]
32
33
# Make request with tools
34
response = client.chat.completions.create(
35
    model="captain-voyager-latest",
36
    messages=[
37
        {"role": "user", "content": "What's the weather in Tokyo?"}
38
    ],
39
    tools=tools
40
)
41
42
# Check if model wants to use a tool
43
if response.choices[0].finish_reason == "tool_calls":
44
    tool_call = response.choices[0].message.tool_calls[0]
45
46
    # Execute tool client-side
47
    import json
48
    args = json.loads(tool_call.function.arguments)
49
    result = get_weather(args["location"], args.get("unit", "celsius"))
50
51
    print(f"Tool used: {tool_call.function.name}")
52
    print(f"Result: {result}")

1
from openai import OpenAI
2
import json
3
4
client = OpenAI(
5
    base_url="https://api.runcaptain.com/v1",
6
    api_key="your_api_key",
7
    default_headers={"X-Organization-ID": "your_org_id"}
8
)
9
10
def calculate(operation, a, b):
11
    """Execute calculation client-side"""
12
    operations = {
13
        "add": lambda x, y: x + y,
14
        "subtract": lambda x, y: x - y,
15
        "multiply": lambda x, y: x * y,
16
        "divide": lambda x, y: x / y if y != 0 else "Error: Division by zero"
17
    }
18
    return {"result": operations[operation](a, b)}
19
20
tools = [{
21
    "type": "function",
22
    "function": {
23
        "name": "calculate",
24
        "description": "Perform arithmetic calculations",
25
        "parameters": {
26
            "type": "object",
27
            "properties": {
28
                "operation": {
29
                    "type": "string",
30
                    "enum": ["add", "subtract", "multiply", "divide"],
31
                    "description": "The operation to perform"
32
                },
33
                "a": {"type": "number", "description": "First number"},
34
                "b": {"type": "number", "description": "Second number"}
35
            },
36
            "required": ["operation", "a", "b"]
37
        },
38
        "strict": True
39
    }
40
}]
41
42
response = client.chat.completions.create(
43
    model="captain-voyager-latest",
44
    messages=[
45
        {"role": "system", "content": "You are a helpful assistant with access to a calculator."},
46
        {"role": "user", "content": "What is 156 multiplied by 243?"}
47
    ],
48
    tools=tools
49
)
50
51
if response.choices[0].finish_reason == "tool_calls":
52
    tool_call = response.choices[0].message.tool_calls[0]
53
    args = json.loads(tool_call.function.arguments)
54
55
    # Execute tool
56
    result = calculate(args["operation"], args["a"], args["b"])
57
    print(f"Calculation result: {result['result']}")

1
from openai import OpenAI
2
3
client = OpenAI(
4
    base_url="https://api.runcaptain.com/v1",
5
    api_key="your_api_key",
6
    default_headers={"X-Organization-ID": "your_org_id"}
7
)
8
9
# Read large document
10
with open('financial_report.txt', 'r') as f:
11
    document = f.read()
12
13
tools = [{
14
    "type": "function",
15
    "function": {
16
        "name": "calculate_total",
17
        "description": "Calculate sum of numbers",
18
        "parameters": {
19
            "type": "object",
20
            "properties": {
21
                "numbers": {
22
                    "type": "array",
23
                    "items": {"type": "number"},
24
                    "description": "List of numbers to sum"
25
                }
26
            },
27
            "required": ["numbers"]
28
        },
29
        "strict": True
30
    }
31
}]
32
33
response = client.chat.completions.create(
34
    model="captain-voyager-latest",
35
    messages=[
36
        {"role": "user", "content": "What is the total revenue from all quarters?"}
37
    ],
38
    tools=tools,
39
    extra_body={
40
        "captain": {
41
            "context": document  # Large document context
42
        }
43
    }
44
)
45
46
if response.choices[0].finish_reason == "tool_calls":
47
    tool_call = response.choices[0].message.tool_calls[0]
48
    args = json.loads(tool_call.function.arguments)
49
50
    # Execute calculation
51
    total = sum(args["numbers"])
52
    print(f"Total revenue: ${total:,.2f}")

1
from openai import OpenAI
2
import json
3
4
client = OpenAI(
5
    base_url="https://api.runcaptain.com/v1",
6
    api_key="your_api_key",
7
    default_headers={"X-Organization-ID": "your_org_id"}
8
)
9
10
def safe_execute_tool(tool_name, args):
11
    """Execute tool with error handling"""
12
    try:
13
        if tool_name == "calculate":
14
            return calculate(args["operation"], args["a"], args["b"])
15
        elif tool_name == "query_db":
16
            return query_database(args["query"])
17
        else:
18
            return {"error": f"Unknown tool: {tool_name}"}
19
    except Exception as e:
20
        return {"error": str(e)}
21
22
response = client.chat.completions.create(
23
    model="captain-voyager-latest",
24
    messages=[{"role": "user", "content": "What is 100 divided by 0?"}],
25
    tools=tools
26
)
27
28
if response.choices[0].finish_reason == "tool_calls":
29
    for tool_call in response.choices[0].message.tool_calls:
30
        args = json.loads(tool_call.function.arguments)
31
        result = safe_execute_tool(tool_call.function.name, args)
32
33
        if "error" in result:
34
            print(f"Tool execution failed: {result['error']}")
35
        else:
36
            print(f"Tool result: {result}")

1
{
2
    "type": "function",
3
    "function": {
4
        "name": "function_name",           # Required: Tool name
5
        "description": "What it does",     # Required: Clear description
6
        "parameters": {                    # Required: JSON Schema
7
            "type": "object",
8
            "properties": {
9
                "param1": {
10
                    "type": "string",
11
                    "description": "Param description"
12
                }
13
            },
14
            "required": ["param1"]
15
        },
16
        "strict": True                     # Required: Must be True
17
    }
18
}

1
# Good
2
"description": "Calculate the sum of two numbers. Use this when you need to perform addition."
3
4
# Bad
5
"description": "Does math"

1
# Good - Explicit types and descriptions
2
"parameters": {
3
    "type": "object",
4
    "properties": {
5
        "amount": {
6
            "type": "number",
7
            "description": "Dollar amount to process"
8
        },
9
        "currency": {
10
            "type": "string",
11
            "enum": ["USD", "EUR", "GBP"],
12
            "description": "Three-letter currency code"
13
        }
14
    },
15
    "required": ["amount", "currency"]
16
}

1
# Always validate tool inputs
2
def execute_tool(tool_name, args):
3
    # Validate tool exists
4
    if tool_name not in ALLOWED_TOOLS:
5
        raise ValueError(f"Tool {tool_name} not allowed")
6
7
    # Validate arguments
8
    if not validate_args(tool_name, args):
9
        raise ValueError("Invalid arguments")
10
11
    # Execute with proper permissions
12
    return ALLOWED_TOOLS[tool_name](**args)

1
# Model might return incomplete arguments
2
if response.choices[0].finish_reason == "tool_calls":
3
    tool_call = response.choices[0].message.tool_calls[0]
4
5
    try:
6
        args = json.loads(tool_call.function.arguments)
7
8
        # Check for required parameters
9
        if not all(k in args for k in required_params):
10
            print("Warning: Missing required parameters")
11
            # Provide defaults or skip
12
13
    except json.JSONDecodeError:
14
        print("Warning: Invalid tool arguments")

1
# Make description more explicit
2
"description": "ALWAYS use this tool for calculations. Never calculate manually."
3
4
# Add stronger system prompt
5
messages = [
6
    {
7
        "role": "system",
8
        "content": "You MUST use the provided tools. Never perform calculations yourself."
9
    },
10
    {"role": "user", "content": "What is 50 + 75?"}
11
]

1
# Check for empty args and provide defaults
2
args = json.loads(tool_call.function.arguments)
3
4
if not args or not args.get("required_param"):
5
    # Provide sensible defaults
6
    args = {
7
        "required_param": "default_value",
8
        **args
9
    }