Function calling y tool-augmented retrieval: el detective que sabe qué archivo pedir

Thu, 04 Jun 2026 10:00:00 +0200

Este post profundiza en el mecanismo de razonamiento agentivo que extiende el RAG descrito en RAG con reranker e hybrid retrieval. El retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline de ese artículo. El JSON Schema que define cada tool call es structured output aplicado a la interfaz herramienta. Y las requests del agente pasan por el gateway L7 de inferencia antes de llegar al modelo.

TL;DR

Un RAG naive consulta siempre la misma fuente. Function calling le da al LLM la capacidad de decidir qué herramienta invocar — vector store, SQL, web search — en función de lo que la query realmente necesita. El patrón ReAct encadena esas invocaciones en un bucle razonado hasta obtener suficiente evidencia. Un pipeline de 3 iteraciones con Llama-3.1-70B en hardware on-premise tarda ≈ 1,1 s frente a los ≈ 300 ms del RAG de un solo paso; la ganancia no es en velocidad sino en queries que el RAG naive simplemente no puede responder. La métrica de eval crítica es tool selection accuracy: el porcentaje de turns en que el modelo elige el tool correcto, medida sobre un eval set sintético.

La analogía: el detective que sabe qué archivo pedir

Un detective de novela no va al mismo archivador independientemente del caso que le llegue. Cuando recibe un caso, razona primero: ¿qué tipo de evidencia necesito? Si hay testigos, pide los testimonios (vector search sobre documentos no estructurados). Si hay transacciones financieras, pide los registros contables al banco (SQL sobre la base de datos estructurada). Si el sospechoso tiene actividad reciente que la empresa no puede tener indexada, va a la hemeroteca (web search). No consulta las tres fuentes de golpe en cada caso: elige la que la evidencia requiere, recibe el resultado, razona de nuevo si necesita más, y sólo cuando tiene suficiente evidencia redacta el informe.

Un detective malo siempre va al mismo archivador. Un RAG naive es ese detective malo: vectoriza la query, va al vector store, y devuelve lo que encuentra aunque la pregunta fuera “¿cuántos contratos?” — algo que ningún chunk de PDF puede responder mejor que un COUNT(*) en SQL.

Function calling es darle al LLM la capacidad de razonar sobre qué fuente pedir, y de invocarla de forma estructurada. La analogía tiene tres aristas que conviene retener:

El detective no improvisa el archivo que pide: hay un catálogo de fuentes disponibles con descripción de qué contiene cada una. La descripción del tool en el system prompt cumple esa función.
El detective puede pedir varias evidencias a la vez si son independientes (parallel tool calling).
El detective sabe cuándo parar: si tras N rondas no llega a conclusión, declara que no tiene suficiente evidencia. El agente tiene un límite de iteraciones por la misma razón.

Qué es function calling: la anatomía de una tool call

Function calling — también llamado tool use — es un mecanismo por el que el LLM, en vez de generar texto libre como respuesta, genera un objeto JSON estructurado que representa una invocación de herramienta. El sistema intercepta ese JSON, ejecuta la herramienta real, y devuelve el resultado como un mensaje de rol tool en la conversación.

Definición de tools en el system prompt

Cada tool se define mediante un JSON Schema que especifica nombre, descripción y parámetros. Este JSON Schema es exactamente el mismo mecanismo descrito en structured output, aplicado aquí a la interfaz herramienta:

{
 "tools": [
 {
 "name": "vector_search",
 "description": "Search internal company documents about policies, contracts and procedures. Use when the query requires unstructured text, document context or semantic similarity.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Natural language search query"},
 "top_k": {"type": "integer", "default": 5}
 },
 "required": ["query"]
 }
 },
 {
 "name": "sql_query",
 "description": "Query the SQL database for structured metrics, counts, aggregations and financial data. Use when the query requires exact numbers, filters, sums or joins over structured records.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string", "description": "Parameterized SQL query with $1, $2 placeholders"},
 "params": {"type": "array", "items": {}, "description": "Parameter values for the placeholders"}
 },
 "required": ["query"]
 }
 },
 {
 "name": "web_search",
 "description": "Search public web for real-time information, recent news or current prices. Use only when data is public and not covered by internal sources.",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 ]
}

El ciclo de una tool call

Cuando el LLM decide invocar una tool, el mensaje que genera en lugar de texto libre tiene esta estructura (formato OpenAI-compatible, el mismo que soporta vLLM):

{
 "role": "assistant",
 "tool_calls": [
 {
 "id": "call_01",
 "type": "function",
 "function": {
 "name": "sql_query",
 "arguments": "{\"query\": \"SELECT COUNT(*), SUM(amount) FROM contracts WHERE amount > $1 AND year = $2 AND provider_region = $3\", \"params\": [100000, 2025, \"EU\"]}"
 }
 }
 ]
}

El sistema ejecuta la tool y devuelve:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"count\": 47, \"total\": 8300000}"}

El LLM recibe ese mensaje como continuación de la conversación y decide si necesita más información o puede generar la respuesta final.

Soporte en modelos OSS

En 2026, el soporte de function calling nativo (no emulado vía system prompt) está disponible en:

Llama 3.1 / 3.3+: formato de tool call nativo, soportado en vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json
Qwen 2.5+: soporte nativo con --tool-call-parser hermes
Mistral NeMo / Mistral 7B Instruct v0.3+: formato nativo con --tool-call-parser mistral
Qwen3 (2025+): soporte nativo extendido con parallel tool calling

Sin --enable-auto-tool-choice, vLLM puede forzar el formato de tool call vía guided decoding (JSON Schema), pero la capacidad de decidir cuándo invocar una tool vs generar texto libre requiere entrenamiento específico del modelo.

El patrón ReAct: Reasoning + Acting

ReAct (Yao et al., 2022) es el bucle que convierte un LLM con tools en un agente con razonamiento. La idea central es que el modelo intercala pensamientos (razonamiento explícito sobre qué hacer) con acciones (invocación de tools) y observaciones (resultados recibidos). Este bucle se repite hasta que el modelo estima tener suficiente información para responder, o hasta que se alcanza el límite de iteraciones.

Thought → Action → Observation → Thought → Action → Observation → ... → Response

Trace ReAct completo: una query de producción real

Query: "¿Cuántos contratos de más de 100k€ firmamos en 2025 con proveedores de la UE, y cuáles son las condiciones especiales que se repiten?"

Esta query requiere dos fuentes distintas: los números exactos viven en SQL, y el contexto de condiciones especiales vive en los PDFs de contratos indexados en el vector store.

Iteración 1

Thought: La query pide datos agregados (conteo y suma) con filtros exactos sobre campos estructurados (importe, año, región). Esto es una consulta SQL, no una búsqueda semántica.

Action: sql_query

SELECT COUNT(*) AS num_contratos, SUM(amount) AS total_eur
FROM contracts
WHERE amount > $1 AND year = $2 AND provider_region = $3

params: [100000, 2025, "EU"]

Observation: {"num_contratos": 47, "total_eur": 8300000}

Iteración 2

Thought: Tengo los números. Ahora necesito las condiciones especiales que se repiten en estos contratos. Ese tipo de información está en el texto libre de los PDFs, no en la tabla estructurada. Voy al vector store.

Action: vector_search

"contratos proveedores UE 2025 importe superior 100k condiciones especiales cláusulas recurrentes"

top_k: 5

Observation:

[chunk_1] Contrato Proveedor A — cláusula 8.3: penalización por retraso del 2% mensual sobre el importe facturado...
[chunk_2] Contrato Proveedor C — cláusula 7.1: revisión de precios vinculada al IPC de la zona euro con tope del 4% anual...
[chunk_3] Contrato Proveedor B — cláusula 8.3: penalización por retraso del 2% mensual...

Thought: Tengo datos suficientes de ambas fuentes. La cláusula 8.3 de penalización por retraso aparece en al menos dos contratos de los recuperados. Puedo sintetizar la respuesta.

Response: “En 2025 firmasteis 47 contratos con proveedores de la UE por importe superior a 100.000 €, con un total acumulado de 8,3 M€. La condición especial que aparece con más frecuencia en los contratos de mayor valor es la cláusula de penalización por retraso (8.3 en los modelos de contrato de Proveedor A y B): 2% mensual sobre importe facturado. También se repite la revisión de precios vinculada al IPC de la zona euro con tope del 4% anual (cláusula 7.1).”

Este trace tiene 2 iteraciones. Una query más compleja (comparar con el año anterior, cruzar con estado de pago) añadiría iteraciones adicionales. La práctica habitual es fijar un límite de 5–10 iteraciones máximo para evitar bucles.

Las tres fuentes y cuándo usar cada una

La elección de fuente no es arbitraria ni queda sólo en manos del LLM: la arquitectura define qué tools existen y cómo se describen. La tabla siguiente resume los criterios de selección:

Característica	Vector store (Qdrant)	SQL / estructurado (PostgreSQL)	Web search
Tipo de dato	Texto libre, documentos, PDFs	Tablas con esquema fijo	Páginas públicas, noticias
Estructura	No estructurado	Altamente estructurado	Semi-estructurado
Temporalidad	Índice estático (actualización periódica)	Tiempo real (transaccional)	Tiempo real (crawl)
Latencia típica	5–50 ms	10–200 ms	200–2.000 ms
Privacidad	Datos internos, soberanía total	Datos internos, soberanía total	Solo datos públicos
Query natural	Sí (lenguaje natural → embedding)	No (SQL parametrizado)	Sí
Agregaciones exactas	No	Sí (`COUNT`, `SUM`, `GROUP BY`)	No
Cuándo usar	Contexto documental, semántica, PDFs	Métricas, conteos, filtros exactos, joins	Datos que no existen internamente y son públicos

La regla práctica más importante: si la pregunta contiene palabras como “cuántos”, “suma”, “total”, “más de X”, “en el año Y” y los datos están en una tabla estructurada, la respuesta correcta es sql_query. Si la pregunta pide contexto, explicaciones, cláusulas, procedimientos o ejemplos de documentos, la respuesta es vector_search. Si pide el precio actual de algo o noticias recientes sobre un tercero, web_search — pero sólo si no hay soberanía de datos implicada.

Tool routing: cómo el LLM elige el tool correcto

La descripción de cada tool en el system prompt es el factor más crítico para la precisión del routing. Un LLM con buenas capacidades de function calling puede elegir mal si las descripciones son ambiguas o se solapan.

Descripciones que funcionan vs las que no

Descripción débil (lleva al LLM a usar el tool equivocado):

"search_docs" — Busca información en las fuentes disponibles.
"query_data" — Obtiene datos del sistema.

Descripción fuerte (delimita con precisión cuándo usar cada uno):

"vector_search" — Search internal company documents about policies, contracts and procedures.
Use when the query requires unstructured text, document context or semantic
similarity. NOT for counts, sums or exact filters.
"sql_query" — Query the SQL database for structured metrics, counts, aggregations and
financial data. Use when the query requires exact numbers, filters, sums or
joins over structured records. NOT for finding document context.

La diferencia está en dos elementos: (1) ejemplos de casos de uso positivos, y (2) exclusiones explícitas con NOT for. Ambos reducen el solapamiento semántico entre tools y mejoran la tool selection accuracy.

Parallel tool calling

Cuando dos tools son independientes entre sí — es decir, el resultado de una no afecta a la query de la otra — el LLM puede invocarlas simultáneamente en el mismo turno:

{
 "tool_calls": [
 {"id": "call_01", "function": {"name": "sql_query", "arguments": "..."}},
 {"id": "call_02", "function": {"name": "vector_search", "arguments": "..."}}
 ]
}

El sistema ejecuta ambas en paralelo y devuelve ambas observaciones antes del siguiente turno del LLM. Esto reduce la latencia total cuando las queries son independientes: en vez de 2 iteraciones secuenciales (2 × latencia_tool), se paga 1 × max(latencia_sql, latencia_vector). Para el ejemplo del detective: si necesita tanto los registros contables como los testimonios para responder, puede pedirlos a la vez.

Tool selection accuracy: la métrica de eval

La tool selection accuracy es el porcentaje de turns en que el LLM elige el tool correcto dado un conjunto de queries evaluadas:

[ \text{TSA} = \frac{\text{turns con tool correcto elegido}}{\text{total turns con tool call esperada}} ]

Se mide sobre un eval set sintético construido con triples (query, tool_esperado, args_esperados). Un ejemplo de eval set mínimo:

Query	Tool esperado	Indicador de fallo
“¿Cuántos pedidos en marzo?”	`sql_query`	LLM usa `vector_search`
“¿Qué dice la política de devoluciones?”	`vector_search`	LLM usa `sql_query`
“¿Cuál es el precio del cobre hoy?”	`web_search`	LLM usa `vector_search`
“Suma los contratos del Q3”	`sql_query`	LLM usa `vector_search`

Una TSA < 0,85 en un agente de producción es señal de que las descripciones de tools necesitan revisión antes que el modelo. Para más detalle sobre cómo construir estos evals, ver evals LLM.

Manejo de errores en tool calls

SQL injection via prompt

El riesgo más serio del tool-augmented retrieval es que el LLM genere SQL malicioso — bien porque un usuario lo indujo via prompt injection, bien porque el modelo alucinó una query destructiva. Este vector de ataque se cubre en detalle en LLM Guard, pero las reglas mínimas del lado del tool son:

Regla 1: Queries parametrizadas siempre, nunca interpolación directa.

# NUNCA esto:
cursor.execute(f"SELECT * FROM contracts WHERE provider = '{llm_output}'")

# Siempre esto:
cursor.execute("SELECT * FROM contracts WHERE provider = $1", [llm_output])

Regla 2: Usuario de BD con permisos mínimos. El usuario con el que el agente ejecuta SQL debe tener SELECT sobre las tablas necesarias y nada más. Ningún DROP, INSERT, UPDATE ni DELETE.

Regla 3: Allowlist de tablas. El sistema valida que la query generada por el LLM sólo referencia tablas en una allowlist antes de ejecutarla.

Regla 4: Timeout por query. Queries que bloquean demasiado tiempo — potencialmente inducidas para hacer DoS a la BD — se cancelan con timeout configurado.

Rate limits, timeouts y errores de tool

Cuando una tool falla, el error se devuelve al LLM como observación:

{"role": "tool", "tool_call_id": "call_01", "content": "{\"error\": \"timeout after 5s\", \"tool\": \"web_search\"}"}

El system prompt debe instruir al LLM sobre qué hacer en este caso:

If a tool returns an error or is unavailable, acknowledge the limitation in your response.
Do not retry more than once. If web_search is unavailable, state that real-time data
is not accessible at this moment and answer with available internal sources only.

Esto evita que el agente entre en bucles de reintentos y gestiona la degradación graceful: si web_search no está disponible, responde con lo que tiene en las fuentes internas.

Diagrama del bucle ReAct con las tres fuentes

Matemáticas de latencia del pipeline ReAct

Cada iteración del bucle ReAct tiene tres componentes de latencia:

[ T_{\text{iter}} = \text{TTFT}{\text{LLM}} + T{\text{tool}} + \Delta_{\text{context}} ]

donde:

TTFT_LLM: tiempo hasta el primer token del LLM (dominado por el prefill del contexto acumulado)
T_tool: tiempo de ejecución de la tool
Δ_context: overhead de context window creciente (cada iteración añade el output anterior al contexto)

Valores de referencia: Llama-3.1-70B en 4×H100 SXM (320 GB, NVLink)

Con Llama-3.1-70B en FP8 en un nodo con 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s), los valores típicos en producción son:

Componente	Valor
TTFT con contexto < 4k tokens	≈ 150 ms
TTFT con contexto 8k tokens	≈ 220 ms
`sql_query` (query simple, índice)	≈ 50 ms
`vector_search` (top-5, Qdrant en RAM)	≈ 20 ms
`web_search` (API externa)	≈ 600 ms

Latencia total según número de iteraciones

Pipeline de 1 iteración (query simple, una sola tool):

[ T_1 = 150 + 50 = 200 \text{ ms} + \text{síntesis final} \approx 200 + 300 = 500 \text{ ms} ]

Pipeline de 2 iteraciones (SQL + vector_search secuenciales):

[ T_2 = (150 + 50) + (180 + 20) + 400 = 800 \text{ ms} ]

El contexto en la segunda iteración ya incluye el resultado de la primera, por lo que el TTFT sube ligeramente a ≈ 180 ms.

Pipeline de 3 iteraciones (el caso más común en queries complejas):

[ T_3 = (150 + 50) + (180 + 20) + (200 + 50) + 450 \approx 1.100 \text{ ms} ]

Parallel tool calling (SQL + vector_search en paralelo, 1 sola iteración):

[ T_{\text{parallel}} = 150 + \max(50, 20) + 400 = 600 \text{ ms} ]

Cuando las dos queries son independientes, el parallel tool calling recorta la latencia de ≈ 800 ms a ≈ 600 ms: un 25% de mejora para el caso de 2 iteraciones secuenciales.

Comparación con RAG naive

Configuración	Latencia	Queries que puede responder
RAG naive (1 retriever, 1 paso)	≈ 300 ms	Queries de contexto documental
ReAct 1 iteración (SQL)	≈ 500 ms	Queries de agregación estructurada
ReAct 2 iteraciones (SQL + vector)	≈ 800 ms	Queries híbridas numérico + contexto
ReAct 3 iteraciones	≈ 1.100 ms	Queries complejas multi-fuente
ReAct con web_search	≈ 1.500 ms	Queries que requieren datos en tiempo real

La conclusión práctica: ReAct multi-hop es 3–5× más lento que un RAG naive de un solo paso. La ganancia no está en la velocidad sino en la cobertura de queries: el RAG naive no puede responder “¿cuántos contratos?” porque esa respuesta no está en ningún chunk de texto. Para aplicaciones con SLO de latencia estricto (< 500 ms), hay que diseñar si el caso de uso realmente necesita ReAct o si un RAG bien configurado con hybrid retrieval cubre el 90% de las queries.

Hardware on-premise para agentes ReAct

Un agente ReAct con Llama-3.1-70B en producción tiene requisitos distintos a un RAG naive porque el contexto crece con cada iteración y el throughput de prefill es más crítico.

Configuración recomendada: 4×H100 SXM (320 GB HBM3, NVLink 900 GB/s)

Llama-3.1-70B en FP8: cabe en 2×H100 (70B params × 1 byte/param ≈ 70 GB + KV cache). Con 4×H100 se puede servir en tensor parallelism TP=4, reduciendo el TTFT por prefill en ≈ 2×.
Instancia de Qdrant: se puede colocar en el mismo nodo (si la colección cabe en RAM) o en nodo dedicado. Para colecciones < 50M vectores de 768 dims: ≈ 150 GB, cabe en RAM de un servidor dual-socket.
PostgreSQL: nodo separado o instancia gestionada. El agente no añade carga inusual al SQL — las queries son simples y acotadas por timeout.
vLLM con --enable-auto-tool-choice --tool-call-parser llama3_json --max-model-len 16384: el contexto de 16k tokens cubre con holgura los 5–10 turns de un pipeline ReAct.

Configuración mínima viable: 2×H100 SXM (160 GB)

Llama-3.1-70B en FP8 en TP=2. TTFT ≈ 250–300 ms para contextos de 4k tokens (aumento del 60–100% sobre TP=4).
Sirve para workloads internos con < 20 requests concurrentes.
No recomendable para SLO < 1 s con más de 5 usuarios concurrentes y contexto largo.

Lo que no hemos cubierto

Agentic retrieval loops con planificación. ReAct es el patrón más simple de agente. Cuando una query requiere descomposición en sub-tareas con dependencias, se necesitan frameworks de orquestación como LangGraph (grafos de estados), smolagents (Hugging Face, agentes con código Python como actions) o llama-index Agents (pipeline de planning + retrieval). Estos introducen un paso de planificación previo al bucle de ejecución.

MCP (Model Context Protocol). El estándar emergente de Anthropic — con implementaciones OSS — para definir tools de forma portable entre frameworks y hosts. En lugar de definir el JSON Schema de cada tool por separado en cada aplicación, MCP centraliza esas definiciones en un servidor MCP que cualquier cliente compatible puede descubrir e invocar. La adopción en 2025–2026 es rápida entre frameworks OSS (LangChain, smolagents, OpenWebUI).

Tool caching. Si el mismo tool call (mismos argumentos, misma tool) se va a invocar múltiples veces dentro del mismo contexto o en contextos muy similares, se puede cachear el resultado. El mecanismo es análogo al semantic cache descrito para RAG: antes de ejecutar el tool, se compara el hash de los argumentos (o su embedding para matching semántico) contra una caché con TTL. Especialmente valioso para sql_query con queries frecuentes y datos que cambian poco.

Multi-agent. Cuando un agente orquestador delega sub-tareas a agentes especializados — uno para SQL, otro para recuperación de documentos, otro para generación de código — se entra en el territorio de los sistemas multi-agente. Cada sub-agente puede tener su propio set de tools y su propio LLM (posiblemente más pequeño y especializado). La coordinación entre agentes introduce complejidad de trazado y observabilidad adicional.

Ver también

RAG con reranker e hybrid retrieval — el retriever que se invoca cuando el LLM elige vector_search es exactamente el pipeline descrito allí: dense + sparse + reranker cruzado
Structured output: fundamentos — el JSON Schema que define el contrato de cada tool call es exactamente structured output aplicado a la interfaz herramienta
Router de inferencia y LLM gateway L7 — el gateway L7 que recibe las requests del agente ReAct y enruta al LLM correcto; también aplica rate limiting por usuario y tenant
LLM Guard: fundamentos — SQL injection via prompt es un vector de ataque real en tool-augmented retrieval; LLM Guard cubre la detección de prompt injection antes de que el request llegue al LLM
Pipeline LLMOps de seis etapas — tool-augmented retrieval vive en la intersección de las etapas Deploy y Observe del pipeline: se despliega como parte del sistema de inferencia y se observa vía tracing de cada turn del agente
Evals LLM: la capa después del tracing — tool selection accuracy es la métrica de eval crítica para un agente ReAct; el golden dataset de eval debe incluir triples (query, tool esperado, args esperados)

Referencias

Yao, S. et al. (2022). ReAct: Synergizing Reasoning and Acting in Language Models. arXiv:2210.03629. https://arxiv.org/abs/2210.03629
vLLM documentation. Tool calling. https://docs.vllm.ai/en/stable/features/tool_calling.html
Qdrant documentation. Search. https://qdrant.tech/documentation/concepts/search/
OpenAI. Function calling. https://platform.openai.com/docs/guides/function-calling
Meta AI. Llama 3.1 Model Card. https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/MODEL_CARD.md
Qwen Team (Alibaba). Qwen2.5 Technical Report. arXiv:2412.15115. https://arxiv.org/abs/2412.15115
Anthropic. Model Context Protocol. https://modelcontextprotocol.io
OWASP. LLM Top 10 for Large Language Model Applications. LLM01: Prompt Injection. https://owasp.org/www-project-top-10-for-large-language-model-applications/

Llama on lo0 — Blog Técnico