Construir un agente que usa herramientas con llamada a funciones

Una sola llamada a función es fácil. Lo interesante es el bucle a su alrededor, porque un modelo rara vez consigue lo que necesita en la primera llamada. Consulta algo, ve el resultado y decide qué pedir a continuación. Este tutorial construye un agente de línea de comandos que responde preguntas sobre una base de datos SQLite que nunca ha visto. No tiene el esquema en su prompt. Recibe tres herramientas de solo lectura y averigua el resto por sí mismo:

python agent.py "Which product brought in the most revenue overall, and which customer spent the most on it?"

Por el camino haremos lo siguiente:

Dar al modelo una base de datos y tres herramientas que la leen
Describir esas herramientas para que el modelo sepa cuándo recurrir a cada una
Ejecutar el bucle que convierte las llamadas a herramientas en resultados de herramientas
Verlo solicitar varias herramientas a la vez
Devolver los errores al modelo en lugar de lanzarlos
Trazar la línea entre lo que el modelo no hará y lo que no puede hacer

La guía de Llamada a funciones cubre la forma de la petición por sí sola. Esta página trata de lo que ocurre después de que llega la primera respuesta.

Configuración

Necesitas Python 3.9 o más reciente, el paquete requests y una clave de API de Venice. Consulta Generar una clave de API si no tienes una. Todo lo demás está en la biblioteca estándar.

pip install requests
export VENICE_API_KEY="your-api-key-here"

Crea agent.py con los imports y el bloque de cabecera que reutiliza cada llamada:

from __future__ import annotations

import json
import os
import sqlite3
import sys

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}
DB_PATH = "shop.db"

No todos los modelos pueden llamar herramientas, y los IDs de los modelos cambian, así que pregunta a la API cuál usar en lugar de fijar un nombre que envejecerá:

def default_tool_model() -> str:
    response = requests.get(f"{BASE_URL}/models/traits", headers=HEADERS, timeout=30)
    response.raise_for_status()
    return response.json()["data"]["function_calling_default"]

print(default_tool_model())

zai-org-glm-5-2

GET /models/traits asigna nombres estables de rasgos al modelo que actualmente cumple ese rol. Leer function_calling_default al iniciar significa que tu agente sigue funcionando cuando se reemplaza el modelo subyacente. Consulta Modelos para ver la lista completa de rasgos.

1. Una base de datos sobre la que valga la pena preguntar

Cualquier archivo SQLite sirve. Este es una pequeña tienda con clientes, productos y los pedidos que los unen, lo suficiente para que una pregunta real necesite un join y una agregación:

SEED = """
CREATE TABLE customers (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    country TEXT NOT NULL,
    signed_up TEXT NOT NULL
);
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    unit_price REAL NOT NULL
);
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER NOT NULL REFERENCES customers(id),
    product_id INTEGER NOT NULL REFERENCES products(id),
    quantity INTEGER NOT NULL,
    ordered_on TEXT NOT NULL
);
INSERT INTO customers VALUES
    (1,'Aria Bekele','ET','2025-11-02'), (2,'Tomas Vidal','ES','2026-01-14'),
    (3,'Mei Lin','SG','2026-02-03'),     (4,'Jonas Weber','DE','2026-02-27'),
    (5,'Priya Nair','IN','2026-03-19');
INSERT INTO products VALUES
    (1,'Field Notebook','stationery',12.5), (2,'Fountain Pen','stationery',48.0),
    (3,'Desk Lamp','lighting',89.0),        (4,'Cable Organiser','desk',9.75),
    (5,'Monitor Arm','desk',156.0);
INSERT INTO orders VALUES
    (1,1,3,2,'2026-04-04'),  (2,2,5,1,'2026-04-11'), (3,3,2,4,'2026-04-19'),
    (4,1,5,2,'2026-05-02'),  (5,4,1,10,'2026-05-08'), (6,5,3,1,'2026-05-21'),
    (7,2,5,3,'2026-06-01'),  (8,3,4,12,'2026-06-09'), (9,5,2,2,'2026-06-15'),
    (10,4,5,1,'2026-06-28');
"""


def build_db() -> None:
    if os.path.exists(DB_PATH):
        return
    db = sqlite3.connect(DB_PATH)
    db.executescript(SEED)
    db.commit()
    db.close()

2. Tres herramientas a las que puede recurrir el modelo

Las herramientas reflejan la forma en la que una persona se enfrenta a una base de datos desconocida: averiguar qué contiene, mirar una tabla de cerca y luego consultarla.

def list_tables() -> str:
    db = sqlite3.connect(DB_PATH)
    rows = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
    ).fetchall()
    db.close()
    return json.dumps([row[0] for row in rows])


def describe_table(table: str) -> str:
    db = sqlite3.connect(DB_PATH)
    rows = db.execute(f"PRAGMA table_info({table})").fetchall()
    db.close()
    if not rows:
        return json.dumps({"error": f"no table named {table}"})
    return json.dumps([{"name": row[1], "type": row[2]} for row in rows])


def run_query(sql: str) -> str:
    if not sql.strip().lower().startswith("select"):
        return json.dumps({"error": "only SELECT statements are allowed"})

    db = sqlite3.connect(DB_PATH)
    try:
        cursor = db.execute(sql)
        columns = [d[0] for d in cursor.description]
        rows = [dict(zip(columns, row)) for row in cursor.fetchmany(50)]
        return json.dumps(rows)
    except (sqlite3.Error, sqlite3.Warning) as error:
        return json.dumps({"error": f"{type(error).__name__}: {error}"})
    finally:
        db.close()

Todas ellas devuelven una cadena JSON, incluyendo los fallos. Es deliberado, y la sección 5 explica por qué. Ahora descríbelas para el modelo. El campo description no es un comentario. Es lo único que lee el modelo al decidir qué herramienta llamar y qué poner en ella:

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_tables",
            "description": "List every table in the shop database.",
            "parameters": {"type": "object", "properties": {}},
        },
    },
    {
        "type": "function",
        "function": {
            "name": "describe_table",
            "description": "Return the column names and types for one table.",
            "parameters": {
                "type": "object",
                "properties": {
                    "table": {"type": "string", "description": "Exact table name."}
                },
                "required": ["table"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "run_query",
            "description": "Run a read-only SQL SELECT against the shop database.",
            "parameters": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "A single SELECT statement."}
                },
                "required": ["sql"],
            },
        },
    },
]

TOOL_IMPLS = {
    "list_tables": lambda: list_tables(),
    "describe_table": lambda table: describe_table(table),
    "run_query": lambda sql: run_query(sql),
}

3. El bucle

La llamada a funciones es una conversación, no una petición. El modelo responde con llamadas a herramientas, tú las ejecutas, añades los resultados y vuelves a preguntar. Termina cuando el modelo responde con contenido en lugar de llamadas.

SYSTEM = (
    "You answer questions about a shop database. "
    "Inspect the schema with the tools before writing a query. "
    "Answer with the figures you retrieved, not from memory."
)


def ask(question: str, model: str, max_rounds: int = 8) -> str:
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]

    for _ in range(max_rounds):
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=HEADERS,
            json={
                "model": model,
                "messages": messages,
                "tools": TOOLS,
                "tool_choice": "auto",
                "temperature": 0,
                "venice_parameters": {"include_venice_system_prompt": False},
            },
            timeout=180,
        )
        response.raise_for_status()
        message = response.json()["choices"][0]["message"]

        calls = message.get("tool_calls") or []
        if not calls:
            return message["content"]

        messages.append(message)
        for call in calls:
            name = call["function"]["name"]
            arguments = json.loads(call["function"]["arguments"] or "{}")
            print(f"  {name}({arguments})", file=sys.stderr)
            messages.append(
                {
                    "role": "tool",
                    "tool_call_id": call["id"],
                    "content": TOOL_IMPLS[name](**arguments),
                }
            )

    raise RuntimeError(f"No answer after {max_rounds} rounds.")

Tres detalles de ese bucle son más importantes de lo que parecen. El mensaje del asistente sin modificar vuelve a messages antes que los resultados. Lleva los tool_calls a los que los resultados están respondiendo, y en un modelo con razonamiento también lleva un campo reasoning_content. Reconstruir el mensaje a mano y descartar campos que no esperabas es la forma más común de romper la segunda ronda. Cada resultado se empareja con su llamada mediante tool_call_id. Nada más lo identifica. max_rounds es un límite real, no una formalidad. Un modelo que sigue consultando sin llegar a una conclusión terminará bucleando hasta que se te acabe la paciencia o el saldo.

Las llamadas a herramientas también llevan un campo index, y resulta tentador usarlo para alinear los resultados con las llamadas. No lo hagas. Cuando el modelo pide tres herramientas a la vez, las tres pueden llegar con el mismo index, porque numera el turno del asistente y no la llamada dentro de él. Solo id es único.

4. Qué hace en realidad

Conecta un bloque principal y ejecútalo:

if __name__ == "__main__":
    build_db()
    question = " ".join(sys.argv[1:]) or "What are the three biggest orders?"
    print(ask(question, default_tool_model()))

python agent.py "Which product brought in the most revenue overall, and which customer spent the most on it?"

Las llamadas a herramientas se imprimen en stderr a medida que ocurren, así que puedes verlo trabajar:

  list_tables({})
  describe_table({'table': 'customers'})
  describe_table({'table': 'orders'})
  describe_table({'table': 'products'})
  run_query({'sql': 'SELECT p.id, p.name, SUM(o.quantity * p.unit_price) AS total_revenue FROM orders o JOIN products p ON o.product_id = p.id GROUP BY p.id, p.name ORDER BY total_revenue DESC LIMIT 1;'})
  run_query({'sql': 'SELECT c.id, c.name, SUM(o.quantity * p.unit_price) AS amount_spent FROM orders o JOIN products p ON o.product_id = p.id JOIN customers c ON o.customer_id = c.id WHERE o.product_id = 5 GROUP BY c.id, c.name ORDER BY amount_spent DESC LIMIT 1;'})

- **Top product by revenue:** **Monitor Arm** (product ID 5) brought in the most
  revenue overall, totaling **$1,092.00**.
- **Top customer for that product:** **Tomas Vidal** (customer ID 2) spent the most
  on the Monitor Arm, contributing **$624.00**, more than half of the product's
  total revenue.

Eso tomó cinco rondas. La forma que tienen merece leerse con atención, porque es todo el argumento a favor del bucle:

Ronda	Qué hizo el modelo
1	Llamó a `list_tables`, ya que no se le había dado ningún esquema
2	Llamó a `describe_table` tres veces en una sola respuesta
3	Escribió la consulta de ingresos, ya conociendo los nombres de las columnas
4	Usó el producto 5 del resultado anterior para escribir una segunda consulta
5	Respondió, sin llamadas a herramientas

La ronda 4 es la parte que una sola llamada a función no puede hacer. El modelo no podía escribir esa consulta hasta haber visto la respuesta a la anterior. Tu ejecución no coincidirá llamada por llamada con esta. A veces el modelo describe las tres tablas a la vez y a veces una por una, y de vez en cuando se salta list_tables y adivina un nombre. Las cifras son estables porque salen de la base de datos; el camino hasta ellas no lo es.

La ronda 2 devolvió tres llamadas a herramientas en una sola respuesta, y el bucle de arriba las ejecuta una detrás de otra. Son independientes, así que un ThreadPoolExecutor merece la pena en cuanto tus herramientas hagan E/S real. Mantén los mensajes tool en el mismo orden que las llamadas que los produjeron.

Cada ronda vuelve a enviar toda la conversación, así que el prompt crece a medida que el agente trabaja. Venice cachea el prefijo estable automáticamente, y el bloque usage muestra cómo compensa:

{"prompt_tokens": 1020, "completion_tokens": 103, "prompt_tokens_details": {"cached_tokens": 960}}

En la última ronda, 960 de 1.020 tokens del prompt se sirvieron desde caché. Prompt caching explica cómo mantener estable ese prefijo.

5. Deja que los errores lleguen al modelo

El instinto es lanzar una excepción ante una consulta incorrecta. Resístelo. Un error es información, y el modelo puede actuar en consecuencia. Pide una tabla que no existe:

python agent.py "How many rows are in the 'purchases' table?"

  run_query({'sql': 'SELECT COUNT(*) AS row_count FROM purchases'})
  list_tables({})

There is no `purchases` table in this database. The available tables are
customers, orders, and products. It's possible that the orders table is what
you're looking for. Would you like me to check the row count there instead?

La primera consulta falló. Como run_query devolvió {"error": "OperationalError: no such table: purchases"} como un resultado de herramienta normal en lugar de lanzar, el modelo lo leyó, llamó a list_tables para averiguar qué sí existía y se corrigió. Si la excepción se hubiera propagado, el script habría muerto por un error tipográfico. Por eso cada herramienta devuelve JSON también en la ruta de error. La regla es sencilla: si a un humano que depura tu herramienta le interesaría ver el mensaje, al modelo también.

6. Lo que no hará y lo que no puede hacer

Pídele al agente que destruya algo:

python agent.py "Delete every order placed by customers in Spain."

Ejecútalo dos veces y puedes obtener dos comportamientos distintos. En una ocasión, se negó antes de tocar una herramienta:

I'm unable to help with that. The tools I have access to are read-only, so I can
only run SELECT queries. I cannot perform DELETE, UPDATE, or INSERT operations.

En otra ocasión fue a buscar primero, ejecutó un SELECT para los clientes españoles, no encontró ninguno porque la columna guarda ES en lugar de Spain, e informó de eso en su lugar:

It turns out there are no orders placed by customers in Spain, so there would be
nothing to delete. If you need to perform deletions, you'll need a tool with
write access.

Ambas respuestas son razonables. Ninguna es un control de seguridad. El modelo leyó la palabra “read-only” en la descripción de una herramienta y decidió respetarla, y un modelo distinto, una conversación más larga o un usuario más insistente pueden llevar a una decisión diferente. La guarda dentro de run_query es la parte que no depende de una decisión:

print(run_query("DELETE FROM orders WHERE customer_id = 2"))
print(run_query("SELECT 1; DROP TABLE orders"))
print(run_query("SELECT COUNT(*) AS n FROM orders"))

{"error": "only SELECT statements are allowed"}
{"error": "Warning: You can only execute one statement at a time."}
[{"n": 10}]

Escribe la descripción para que el modelo rara vez lo intente. Escribe la guarda para que no importe cuando lo intente.

Esa segunda línea es la razón por la que run_query captura sqlite3.Warning junto con sqlite3.Error. El driver de Python rechaza sentencias apiladas, pero lanza Warning para ellas, y Warning no es una subclase de Error. Capturar solo sqlite3.Error deja que una sentencia apilada escape del handler y mate el bucle en lugar de devolver un mensaje que el modelo pueda leer.

Una comprobación de prefijo detiene las escrituras, pero no dice nada sobre las lecturas. Cualquier SELECT que escriba el modelo puede alcanzar cualquier tabla del archivo, incluidas algunas que nunca quisiste exponer. Merece la pena hacer dos cambios antes de que esto toque datos reales: abre la base de datos en solo lectura con sqlite3.connect("file:shop.db?mode=ro", uri=True), que falla las escrituras con attempt to write a readonly database sin importar lo que la comprobación de cadena se le pase, y apunta al agente a una base de datos o a un conjunto de vistas que contengan únicamente las columnas que se le permite ver.

Controlar cuándo se usan las herramientas

tool_choice decide cuánta voz tiene el modelo:

Valor	Comportamiento
`"auto"`	Decide el modelo. El valor por defecto correcto
`"required"`	El modelo debe llamar a algo antes de poder responder
`"none"`	Las herramientas son visibles pero no están disponibles; útil para un turno final de resumen
`{"type": "function", "function": {"name": "run_query"}}`	Fuerza una herramienta concreta

"required" es más contundente de lo que parece. Preguntar a este agente What is 2 + 2? con tool_choice en "required" hace que llame a list_tables, mire una base de datos que no le sirve de nada y luego responda 4 en la siguiente ronda. Con "auto" responde 4 de inmediato y no llama a nada. Recurre a "required" cuando una herramienta realmente deba ejecutarse, por ejemplo para registrar una petición, y déjalo en paz en el resto de casos.

Ajustar el agente

Objetivo	Qué cambiar
Menos rondas	Pon el esquema en el system prompt para que el modelo pueda saltarse la fase de descubrimiento
Menor coste	Reduce `fetchmany(50)`, ya que los conjuntos de resultados anchos dominan el prompt a medida que se acumulan las rondas
Argumentos más fiables	Añade `"strict": true` a la definición de la función para restringir los argumentos al esquema
Pasos anchos más rápidos	Ejecuta las llamadas a herramientas en paralelo de forma concurrente, o pon `parallel_tool_calls` en `false` para detenerlas
Menos divagación	Baja `max_rounds` y di en el system prompt cuántas consultas son razonables

Próximos pasos

El bucle que ahora tienes es el mismo que hay detrás de la mayoría de agentes. Solo cambian las herramientas.

Cambia las herramientas SQL por llamadas HTTP y se convierte en un agente de API.
Añade Web Search y scraping como herramienta y podrá consultar la web en vivo a mitad de la respuesta.
Pide un resultado tipado en lugar de prosa con Respuestas estructuradas.
Consulta una versión más grande de este patrón en el Private Research Agent.

Llamada a funciones

Referencia para el array de tools y tool_choice.

Respuestas estructuradas

Restringe la respuesta final a un esquema JSON.

Prompt caching

Mantén barata la conversación creciente.

Private Research Agent

El mismo bucle con herramientas web y un planificador.

Documentación

Primeros pasos

Texto y chat

Imagen

Vídeo

Audio

Búsqueda y RAG

Agentes e integraciones

Herramientas de código

Herramientas para agentes

SDK y frameworks

Construir un agente que usa herramientas con llamada a funciones

Configuración

1. Una base de datos sobre la que valga la pena preguntar

2. Tres herramientas a las que puede recurrir el modelo

3. El bucle

4. Qué hace en realidad

5. Deja que los errores lleguen al modelo

6. Lo que no hará y lo que no puede hacer

Controlar cuándo se usan las herramientas

Ajustar el agente

Próximos pasos

Llamada a funciones

Respuestas estructuradas

Prompt caching

Private Research Agent

​Configuración

​1. Una base de datos sobre la que valga la pena preguntar

​2. Tres herramientas a las que puede recurrir el modelo

​3. El bucle

​4. Qué hace en realidad

​5. Deja que los errores lleguen al modelo

​6. Lo que no hará y lo que no puede hacer

​Controlar cuándo se usan las herramientas

​Ajustar el agente

​Próximos pasos

Llamada a funciones

Respuestas estructuradas

Prompt caching

Private Research Agent

Configuración

1. Una base de datos sobre la que valga la pena preguntar

2. Tres herramientas a las que puede recurrir el modelo

3. El bucle

4. Qué hace en realidad

5. Deja que los errores lleguen al modelo

6. Lo que no hará y lo que no puede hacer

Controlar cuándo se usan las herramientas

Ajustar el agente

Próximos pasos