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

# Llamadas a funciones

> Permite que un modelo elija herramientas, devuelva argumentos estructurados y continúe después de que tu aplicación ejecute la herramienta.

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

1. Envía el mensaje del usuario y una lista de herramientas disponibles.
2. El modelo devuelve una o más llamadas a herramientas con argumentos en JSON.
3. Tu aplicación valida y ejecuta las llamadas a herramientas.
4. Envía los resultados de las herramientas como mensajes `tool`.
5. 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.

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```python theme={null}
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.

```javascript theme={null}
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.

## Próximos pasos

* [Salida estructurada](/es/guide/structured-output)
* [Modelos de razonamiento](/es/guide/reasoning)