Llamadas a funciones

Las llamadas a funciones, también llamadas llamadas a herramientas (tool calling), permiten que un modelo decida cuándo llamar a una función externa y qué argumentos pasarle. El modelo no ejecuta la función. Tu aplicación es quien la ejecuta, envía el resultado de vuelta y le pide al modelo que produzca la respuesta final. Usa las llamadas a funciones para crear asistentes que puedan consultar bases de datos, verificar el estado de un pedido, obtener el clima, buscar en sistemas internos o activar acciones controladas.

Flujo de trabajo

Envía el mensaje del usuario y una lista de herramientas disponibles.
El modelo devuelve una o más llamadas a herramientas con argumentos en JSON.
Tu aplicación valida y ejecuta las llamadas a herramientas.
Envía los resultados de las herramientas como mensajes tool.
El modelo usa los resultados para generar la respuesta final.

Definir herramientas

Declara las herramientas disponibles en el arreglo tools. Cada función usa JSON Schema para sus argumentos.

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "What is the weather in Beijing today?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name, such as Beijing or Shanghai"
            }
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

tool_choice controla la selección de herramientas:

auto: el modelo decide si llama a una herramienta.
none: la llamada a herramientas está deshabilitada para esta solicitud.
{"type":"function","function":{"name":"get_weather"}}: obliga a usar una función específica.

Leer la llamada a la herramienta

Cuando el modelo quiere llamar a una herramienta, devuelve tool_calls:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"Beijing\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Analiza function.arguments como JSON y conserva el id. Necesitarás ese ID al devolver el resultado de la herramienta.

Devolver resultados de herramientas

Después de que tu aplicación ejecute get_weather, agrega un mensaje tool usando el tool_call_id correspondiente:

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temp\": \"25 C\", \"condition\": \"sunny\"}"
}

Luego envía la conversación completa de vuelta al modelo para que pueda producir la respuesta final.

Ejemplo completo en Python

Reemplaza sk-your-key en API_KEY con tu clave real. El ejemplo omite las variables de entorno del proxy del sistema y se conecta directamente a Moxus AI.

import json
import httpx
from openai import OpenAI

API_KEY = "sk-your-key"

client = OpenAI(
    api_key=API_KEY,
    base_url="https://moxus.ai/v1",
    # Connect directly to Moxus AI without reading system or terminal proxy variables.
    http_client=httpx.Client(trust_env=False, timeout=60.0),
)

def get_weather(city: str) -> dict:
    return {"temp": "25 C", "condition": "sunny"}

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    }
]

messages = [{"role": "user", "content": "What is the weather in Beijing today?"}]

response = client.chat.completions.create(
    model="gpt-5.4-mini",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message

if message.tool_calls:
    messages.append(message)
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)
        result = get_weather(**args)
        messages.append(
            {
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            }
        )

    final = client.chat.completions.create(
        model="gpt-5.4-mini",
        messages=messages,
        tools=tools,
    )
    print(final.choices[0].message.content)
else:
    print(message.content)

Ejemplo completo en Node.js

Reemplaza sk-your-key en API_KEY con tu clave real. Este ejemplo ejecuta únicamente la función declarada get_weather. No ejecutes nombres de funciones ni argumentos arbitrarios devueltos por un modelo.

import OpenAI from "openai";

const API_KEY = "sk-your-key";

const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: "https://moxus.ai/v1",
});

function getWeather(city) {
  // Call a real weather API here in production.
  return { temp: "25 C", condition: "sunny", city };
}

const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a city",
      parameters: {
        type: "object",
        properties: {
          city: { type: "string", description: "City name" },
        },
        required: ["city"],
      },
    },
  },
];

const messages = [{ role: "user", content: "What is the weather in Beijing today?" }];

const response = await client.chat.completions.create({
  model: "gpt-5.4-mini",
  messages,
  tools,
  tool_choice: "auto",
});

const message = response.choices[0].message;

if (message.tool_calls?.length) {
  messages.push(message);

  for (const call of message.tool_calls) {
    if (call.function.name !== "get_weather") {
      throw new Error(`Tool is not allowed: ${call.function.name}`);
    }

    const args = JSON.parse(call.function.arguments);
    const result = getWeather(args.city);
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(result),
    });
  }

  const final = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages,
    tools,
  });
  console.log(final.choices[0].message.content);
} else {
  console.log(message.content);
}

Notas

Valida los argumentos antes de ejecutar una función.
Devuelve los resultados de las herramientas como cadenas de texto, generalmente JSON serializado.
Un modelo puede solicitar varias llamadas a herramientas en una sola respuesta.
El soporte de llamadas a herramientas depende del modelo seleccionado.
Cada ronda adicional consume tokens, así que mantén las salidas de las herramientas concisas.

Descripción general

Plataforma

Guías

Integraciones

Llamadas a funciones

Flujo de trabajo

Definir herramientas

Leer la llamada a la herramienta

Devolver resultados de herramientas

Ejemplo completo en Python

Ejemplo completo en Node.js

Notas

Próximos pasos

​Flujo de trabajo

​Definir herramientas

​Leer la llamada a la herramienta

​Devolver resultados de herramientas

​Ejemplo completo en Python

​Ejemplo completo en Node.js

​Notas

​Próximos pasos

Flujo de trabajo

Definir herramientas

Leer la llamada a la herramienta

Devolver resultados de herramientas

Ejemplo completo en Python

Ejemplo completo en Node.js

Notas

Próximos pasos