> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Calling

> Function calling and tool execution capabilities

Tool calling allows AI models to execute functions and interact with external systems, enabling more dynamic and powerful applications.

## Basic Tool Calling

### Simple Function Definition

Define a tool within your application that the AI model can call.

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  function getWeather(location: string): string {
    // This would normally call a real weather API
    return `The weather in ${location} is sunny and 75°F`;
  }

  // Define the tool for the AI
  const tools = [
    {
      type: "function" as const,
      function: {
        name: "get_weather",
        description: "Get current weather information for a location",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state, e.g. San Francisco, CA"
            }
          },
          required: ["location"]
        }
      }
    }
  ];

  async function basicToolCalling() {
    try {
      const response = await sudo.router.create({
        model: "gpt-4o",
        messages: [
          { role: "user", content: "What's the weather like in New York?" }
        ],
        tools: tools,
        toolChoice: "auto"
      });
      
      const message = response.choices[0].message;
      
      // Check if the model wants to call a function
      if (message.toolCalls) {
        for (const toolCall of message.toolCalls) {
          if (toolCall.function.name === "get_weather") {
            const args = JSON.parse(toolCall.function.arguments);
            const weatherResult = getWeather(args.location);
            console.log(`Weather result: ${weatherResult}`);
          }
        }
      } else {
        console.log(`Response: ${message.content}`);
      }
    } catch (error) {
      console.error("Tool calling error:", error);
    }
  }

  basicToolCalling();
  ```

  ```python Python theme={null}
  import os
  import json
  from sudo import Sudo

  def get_weather(location):
      """Get current weather for a location"""
      # This would normally call a real weather API
      return f"The weather in {location} is sunny and 75°F"

  # Define the tool for the AI
  tools = [
      {
          "type": "function",
          "function": {
              "name": "get_weather",
              "description": "Get current weather information for a location",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {
                          "type": "string",
                          "description": "The city and state, e.g. San Francisco, CA"
                      }
                  },
                  "required": ["location"]
              }
          }
      }
  ]

  with Sudo(
      server_url="https://sudoapp.dev/api",
      api_key=os.getenv("SUDO_API_KEY"),
  ) as client:
      response = client.router.create(
          model="gpt-4o",
          messages=[
              {"role": "user", "content": "What's the weather like in New York?"}
          ],
          tools=tools,
          tool_choice="auto"
      )
      
      message = response.choices[0].message
      
      # Check if the model wants to call a function
      if message.tool_calls:
          for tool_call in message.tool_calls:
              if tool_call.function.name == "get_weather":
                  args = json.loads(tool_call.function.arguments)
                  weather_result = get_weather(args["location"])
                  print(f"Weather result: {weather_result}")
      else:
          print(f"Response: {message.content}")
  ```
</CodeGroup>

## Streaming with Tools

<CodeGroup dropdown>
  ```typescript TypeScript theme={null}
  import { Sudo } from "sudo-ai";

  const sudo = new Sudo({
    serverURL: "https://sudoapp.dev/api",
    apiKey: process.env.SUDO_API_KEY ?? "",
  });

  async function streamWithToolCalls() {
    const tools = [
      {
        type: "function" as const,
        function: {
          name: "search_database",
          description: "Search for information in the database",
          parameters: {
            type: "object",
            properties: {
              query: { 
                type: "string", 
                description: "Search query" 
              }
            },
            required: ["query"]
          }
        }
      }
    ];
    
    try {
      const stream = await sudo.router.createStreaming({
        model: "gpt-4o",
        messages: [
          { role: "user", content: "Find information about TypeScript frameworks" }
        ],
        tools: tools,
        toolChoice: "auto"
      });
      
      const toolCalls: any[] = [];
      const contentParts: string[] = [];
      
      for await (const chunk of stream) {
        if (chunk.data?.choices) {
          for (const choice of chunk.data.choices) {
            if (choice.delta) {
              // Regular content
              if (choice.delta.content) {
                const content = choice.delta.content;
                contentParts.push(content);
                process.stdout.write(content);
              }
              
              // Tool calls
              if (choice.delta.toolCalls) {
                for (const toolCallDelta of choice.delta.toolCalls) {
                  // Handle streaming tool calls
                  console.log(`\n[Tool Call: ${toolCallDelta.function?.name}]`);
                  if (toolCallDelta.function?.arguments) {
                    console.log(`[Args: ${toolCallDelta.function.arguments}]`);
                  }
                }
              }
            }
          }
        }
      }
      
      console.log();
    } catch (error) {
      console.error("Streaming tool calling error:", error);
    }
  }

  streamWithToolCalls();
  ```

  ```python Python theme={null}
  import os
  import json
  from sudo import Sudo

  def stream_with_tool_calls():
      tools = [
          {
              "type": "function",
              "function": {
                  "name": "search_database", 
                  "description": "Search for information in the database",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "query": {"type": "string", "description": "Search query"}
                      },
                      "required": ["query"]
                  }
              }
          }
      ]
      
      with Sudo(
          server_url="https://sudoapp.dev/api",
          api_key=os.getenv("SUDO_API_KEY"),
      ) as client:
          
          stream = client.router.create_streaming(
              model="gpt-4o",
              messages=[
                  {"role": "user", "content": "Find information about Python frameworks"}
              ],
              tools=tools,
              tool_choice="auto"
          )
          
          tool_calls = []
          content_parts = []
          
          with stream as event_stream:
              for chunk in event_stream:
                  if chunk.data and chunk.data.choices:
                      for choice in chunk.data.choices:
                          if choice.delta:
                              # Regular content
                              if choice.delta.content:
                                  content = choice.delta.content
                                  content_parts.append(content)
                                  print(content, end="", flush=True)
                              
                              # Tool calls
                              if choice.delta.tool_calls:
                                  for tool_call_delta in choice.delta.tool_calls:
                                      # Handle streaming tool calls
                                      print(f"\n[Tool Call: {tool_call_delta.function.name}]")
                                      if tool_call_delta.function.arguments:
                                          print(f"[Args: {tool_call_delta.function.arguments}]")
          
          print()

  stream_with_tool_calls()
  ```
</CodeGroup>

## Next Steps

1. **[Structured Output](/sdk/sudo-sdk/structured-output)** - Generate JSON and structured data
2. **[Image Input](/sdk/sudo-sdk/image-input)** - Work with multimodal inputs
3. **[Reasoning](/sdk/sudo-sdk/reasoning)** - Advanced reasoning capabilities

<Tip>
  Tool calling works best with models like GPT-4o, Claude Sonnet-4, and other function-calling capable models. Always validate tool inputs and handle errors gracefully. Both TypeScript and Python SDKs provide the same powerful tool calling capabilities with language-appropriate patterns.
</Tip>