Ir al contenido principal
Español— Elegir un idioma
Menú

Combinar herramientas en una única llamada

Lección 19 de 20 Actualizado el 2 de noviembre de 2026 Desarrollador
En esta página
  1. Combinar herramientas en una única llamada
  2. Principio de combinación
  3. Ejemplo completo: asistente analítico
  4. Gestionar el bucle de múltiples herramientas
  5. Estrategias de orquestación
  6. Patrón: agente multi-competencia
  7. Puntos clave

Actualizado el 2 de noviembre de 2026 según la documentación de OpenAI: la herramienta Code Interpreter requiere ahora un parámetro container (añadido a todos los ejemplos), las partes de entrada de texto usan el tipo input_text, y la búsqueda web utiliza la herramienta web_search (web_search_preview es ahora una herramienta heredada sin filtros de dominio). Los archivos generados se recuperan mediante las funciones fichiers_generes y telecharger de la Lección 10. Los archivos adjuntos a un mensaje se suben con el propósito user_data, que OpenAI recomienda para las entradas del modelo (File inputs). Fuentes: Code Interpreter · Web search.

Combinar herramientas en una única llamada

Hasta ahora, hemos examinado cada herramienta de forma aislada. En producción, las preguntas interesantes rara vez adoptan esa forma. Preguntar «¿cómo se comparan nuestras ventas con el mercado?» requiere obtener una cifra interna, una externa y, a continuación, compararlas. Tres herramientas, tres fuentes, una llamada.

Lo que cambia es quién decide el orden. No programas la secuencia: declaras las herramientas disponibles y describes el resultado esperado, y el modelo establece su propio plan. Esto resulta cómodo, pero también es el punto que debes vigilar: un plan implícito es un plan que no puedes revisar. La última parte de esta lección muestra cómo recuperar el control cuando el orden es realmente importante.

Principio de combinación

Todas las herramientas se declaran en el mismo array tools, y ese es todo el mecanismo: no existe una API de composición, solo una lista de capacidades disponibles. El modelo lee tu solicitud, infiere los pasos necesarios y llama a lo que necesita, en el orden que considere útil. Una herramienta que se declara pero no es necesaria para la tarea simplemente no se llamará; no cuesta nada más allá de los pocos tokens de su descripción.

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Compare our sales forecasts with market trends, "
          "then create a comparison chart.",
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_previsions"]},
        {"type": "web_search"},
        {"type": "code_interpreter", "container": {"type": "auto"}}
    ]
)

El modelo hará lo siguiente:

  1. Obtener las previsiones internas mediante File Search
  2. Obtener las tendencias del mercado mediante Web Search
  3. Generar un gráfico de comparación mediante Code Interpreter

Ejemplo completo: asistente analítico

with open("donnees_ventes.csv", "rb") as f:
    fichier = client.files.create(file=f, purpose="user_data")

tools = [
    # Buscar documentos internos
    {
        "type": "file_search",
        "vector_store_ids": ["vs_rapports", "vs_objectifs"],
        "max_num_results": 10
    },
    # Búsqueda web para contexto de mercado
    {
        "type": "web_search",
        "search_context_size": "medium"
    },
    # Ejecución de código para análisis
    {"type": "code_interpreter", "container": {"type": "auto"}},
    # Función para guardar el informe
    {
        "type": "function",
        "name": "sauvegarder_rapport",
        "description": "Save an analysis report to the document system",
        "parameters": {
            "type": "object",
            "properties": {
                "titre": {"type": "string"},
                "contenu": {"type": "string"},
                "categorie": {
                    "type": "string",
                    "enum": ["analyse", "prevision", "audit", "comparaison"]
                },
                "tags": {
                    "type": "array",
                    "items": {"type": "string"}
                }
            },
            "required": ["titre", "contenu", "categorie", "tags"],
            "additionalProperties": False
        },
        "strict": True
    }
]

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": (
                "Based on this sales file: "
                "1. Analyze trends over the last 12 months "
                "2. Compare with our annual goals (search the docs) "
                "3. Search the web for market trends "
                "4. Generate a comparison chart "
                "5. Write a summary report "
                "6. Save the report"
            )},
            {"type": "input_file", "file_id": fichier.id}
        ]
    }],
    tools=tools,
    instructions=(
        "You are a senior business analyst. "
        "Use all tools at your disposal to produce "
        "a complete, sourced analysis."
    )
)

Gestionar el bucle de múltiples herramientas

Existe una asimetría que debes tener presente, ya que determina la estructura de tu código. Las herramientas integradas (Web Search, File Search, Code Interpreter) se ejecutan en OpenAI: el modelo las llama, obtiene el resultado y continúa, todo en un único viaje de ida y vuelta. Sin embargo, tus funciones personalizadas se ejecutan en tu lado: el modelo solo puede solicitar su ejecución, luego cede el control y espera.

De ahí el siguiente bucle. Mientras la respuesta contenga llamadas a funciones, debes ejecutarlas, devolver los resultados y reiniciar. Establece un número máximo de iteraciones: un modelo que vuelva a llamar indefinidamente a la misma herramienta porque el resultado no le satisface es un caso raro pero real, y sin una barrera de seguridad consumirá tu presupuesto hasta agotarlo.

import json

def boucle_multi_outils(prompt, tools, fichiers=None, max_tours=15):
    """Function calling loop with multi-tool support."""
    content = [{"type": "input_text", "text": prompt}]
    if fichiers:
        for fid in fichiers:
            content.append({"type": "input_file", "file_id": fid})

    messages = [{"role": "user", "content": content}]

    for tour in range(max_tours):
        response = client.responses.create(
            model="gpt-5.6-terra",
            input=messages,
            tools=tools,
            instructions="Use the necessary tools to answer completely."
        )

        # Built-in tools (web_search, file_search, code_interpreter)
        # are executed automatically on the server side.
        # We only handle custom function_call items.
        appels_custom = [
            item for item in response.output
            if item.type == "function_call"
        ]

        if not appels_custom:
            # No custom call: the model is finished
            return {
                "reponse": response.output_text,
                "tours": tour + 1,
                "tokens": response.usage.total_tokens
            }

        # Execute custom functions
        resultats = []
        for appel in appels_custom:
            resultat = dispatcher_fonctions(appel.name, appel.arguments)
            resultats.append({
                "type": "function_call_output",
                "call_id": appel.call_id,
                "output": json.dumps(resultat)
            })

        # Prepare the next turn
        messages = response.output + resultats

    return {"reponse": "Turn limit reached", "tours": max_tours}

Estrategias de orquestación

Guiar el orden de las herramientas

La orquestación automática funciona bien mientras el orden no importe. Deja de funcionar cuando un paso debe informar al siguiente: buscar en tus documentos antes que en la web, por ejemplo, porque el vocabulario interno condiciona la relevancia de la consulta externa. El mensaje del sistema es la palanca: no como una restricción técnica, sino como una instrucción metodológica que el modelo seguirá mejor cuando esté justificada.

# Estrategia 1: buscar primero, actuar después
instructions_recherche_dabord = (
    "Before any action, first search for the necessary information "
    "in internal documents and on the web. "
    "Do not propose actions until you have gathered all data."
)

# Estrategia 2: análisis de datos y luego enriquecimiento
instructions_analyse_dabord = (
    "Start by analyzing the data with Code Interpreter. "
    "Then enrich your conclusions with web searches. "
    "Finally, compare with internal documents."
)

# Estrategia 3: verificación cruzada
instructions_verification = (
    "For each important piece of information, verify it in at least two sources: "
    "internal documents AND web search. Report any contradictions."
)

Limitar herramientas por paso

El enfoque opuesto consiste en eliminar la elección. En lugar de una única llamada con el kit de herramientas completo, divides el flujo de trabajo en varias llamadas, declarando en cada una solo la herramienta para su paso específico. Pierdes la orquestación automática, pero ganas tres cosas importantes en producción: orden garantizado, coste predecible y errores aislables. Para un flujo crítico, esta es casi siempre la compensación correcta.

# Paso 1: recopilación de datos (sin código)
response_collecte = client.responses.create(
    model="gpt-5.6-terra",
    input="Gather information on Project Alpha",
    tools=[
        {"type": "file_search", "vector_store_ids": ["vs_projets"]},
        {"type": "web_search"}
    ]
)

# Paso 2: análisis con los datos recopilados
response_analyse = client.responses.create(
    model="gpt-5.6-terra",
    input=f"Analyze this information and generate charts:\n"
          f"{response_collecte.output_text}",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}]
)

Patrón: agente multi-competencia

Este último ejemplo combina ambos enfoques: un enrutador selecciona la configuración de herramientas según la naturaleza de la solicitud y, a continuación, deja que el modelo orqueste dentro de ese ámbito restringido. Es el compromiso que se mantiene en el uso: suficiente libertad para absorber la variedad de solicitudes y suficiente estructura para mantener los costes y el comportamiento predecibles.

class AgentMultiCompetences:
    def __init__(self, vector_stores: list[str], fonctions: list[dict]):
        self.client = OpenAI()
        self.tools = [
            {"type": "file_search", "vector_store_ids": vector_stores},
            {"type": "web_search", "search_context_size": "medium"},
            {"type": "code_interpreter", "container": {"type": "auto"}},
        ] + fonctions

    def traiter(self, requete: str, fichiers: list[str] = None) -> dict:
        return boucle_multi_outils(requete, self.tools, fichiers)

# Instanciar el agente
agent = AgentMultiCompetences(
    vector_stores=["vs_docs", "vs_contrats"],
    fonctions=[
        {
            "type": "function",
            "name": "envoyer_email",
            "description": "Send a notification email",
            "parameters": {
                "type": "object",
                "properties": {
                    "destinataire": {"type": "string"},
                    "sujet": {"type": "string"},
                    "corps": {"type": "string"}
                },
                "required": ["destinataire", "sujet", "corps"],
                "additionalProperties": False
            },
            "strict": True
        },
        {
            "type": "function",
            "name": "creer_tache",
            "description": "Create a task in the project manager",
            "parameters": {
                "type": "object",
                "properties": {
                    "titre": {"type": "string"},
                    "assignee": {"type": "string"},
                    "priorite": {"type": "string", "enum": ["basse", "moyenne", "haute"]},
                    "echeance": {"type": "string"}
                },
                "required": ["titre", "assignee", "priorite"],
                "additionalProperties": False
            },
            "strict": True
        }
    ]
)

# El agente ahora puede:
# - Buscar documentos
# - Buscar en la web
# - Analizar datos
# - Enviar correos electrónicos
# - Crear tareas
resultat = agent.traiter(
    "Analyze Q1 sales, compare with goals, "
    "and create a task for the sales director if we are behind."
)

Puntos clave

  • Todas las herramientas coexisten en el mismo array tools
  • Las herramientas integradas se ejecutan en el servidor; las funciones personalizadas, en el cliente
  • El modelo orquesta automáticamente el orden de las llamadas
  • Guía la estrategia de orquestación mediante el mensaje del sistema
  • Implementa un bucle para gestionar las llamadas a funciones personalizadas