Build an agent with tools

Give a SAGEA model access to external functions it can call mid-conversation.

Define a tool schema that describes your function
Send a message that triggers a tool call
Execute the function locally and feed the result back to the model

The pattern works for any data source: APIs, databases, or internal services.

Time to complete: ~10 minutes

Prerequisites

A SAGEA API key (see Get your API key if you don't have one yet)
Python 3.9+ or Node.js 18+ installed
The SAGEA SDK installed (see Install the SDK if you haven't yet)

Step 1: Define a tool

Define the function the model can call. This example creates a get_weather tool that accepts a city name.

import json
import os
import sagea
 
client = sagea.Client(api_key=os.environ["SAGEA_API_KEY"])
 
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a given city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "The city name, e.g. 'Kathmandu'."}
                },
                "required": ["city"]
            }
        }
    }
]

Step 2: Send a request with the tool

Ask the model a question that requires the tool. The model returns a tool_calls response instead of a text answer.

messages = [
    {"role": "user", "content": "What's the weather in Kathmandu today?"}
]
 
response = client.chat.completions.create(
    model="sage-2-4-actus",
    messages=messages,
    tools=tools,
)
 
tool_call = response.choices[0].message.tool_calls[0]
print(f"Model wants to call: {tool_call.function.name}")
print(f"With arguments: {tool_call.function.arguments}")

Direct API equivalent:

curl -X POST https://api.sagea.space/v1/chat/completions \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-2-4-actus",
    "messages": [{"role": "user", "content": "What is the weather in Kathmandu?"}],
    "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Get weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]
  }'

Step 3: Execute the function and return the result

Run your function with the model's arguments, then send the result back so the model can generate a natural-language answer.

def get_weather(city: str) -> dict:
    return {"city": city, "temperature": "18°C", "condition": "Partly cloudy"}
 
args = json.loads(tool_call.function.arguments)
result = get_weather(**args)
 
messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "name": tool_call.function.name,
    "content": json.dumps(result),
    "tool_call_id": tool_call.id,
})
 
final_response = client.chat.completions.create(
    model="sage-2-4-actus",
    messages=messages,
    tools=tools,
)
 
print(final_response.choices[0].message.content)
# "The weather in Kathmandu is 18°C and partly cloudy."

Verify

A successful run prints a natural-language response that includes the tool's return value. The model:

Detected the request needed external data
Generated a structured tool_calls request
Incorporated your function's result into a conversational answer

Set tool_choice: "any" to force the model to always call a tool, or use tool_choice: "auto" (default) to let the model decide.