Llamadas a herramientas y salida estructurada en Gemini API: guía para arquitectura

¿Qué aprenderás en esta guía?

Verás para qué sirven las llamadas a herramientas y la salida estructurada en Gemini API, en qué tareas puede convenir cada enfoque y cómo diseñar un ejemplo orientado a la arquitectura. La guía se centra en recopilar datos de espacios a partir de notas de proyectos y hacer que el modelo genere los parámetros necesarios para una función externa.

Estas dos funciones no son lo mismo. En las llamadas a funciones, el modelo evalúa si debe invocarse una de las funciones definidas y devuelve los parámetros necesarios. Con la salida estructurada, se le pide que genere una respuesta conforme a un esquema predefinido. La primera está orientada a interactuar con herramientas y la segunda, a obtener datos ordenados; pueden utilizarse en distintas etapas del mismo flujo de trabajo cuando sea necesario.

Requisitos

La documentación de Gemini API de Google incluye ejemplos de SDK para Python y JavaScript, además de ejemplos para Java, Go y REST. El ejemplo de Python utiliza el cliente genai del paquete google, mientras que el de JavaScript usa el paquete @google/genai. En el ejemplo de REST, la clave de API se pasa mediante la variable GEMINI_API_KEY. Como las fuentes no explican los pasos de instalación, las tarifas ni las condiciones de las cuentas, no conviene hacer suposiciones al respecto; antes de implementar la solución, consulta por separado la información actualizada sobre acceso a la API y precios.

El nombre del modelo utilizado en los ejemplos es gemini-3.8-flash. La elección del modelo debe responder a los requisitos de la aplicación; el ejemplo de esta guía sigue el nombre del modelo indicado en la documentación fuente. Los equipos que trabajen con código deben tener preparado el SDK correspondiente al lenguaje que utilizan y acceso a Gemini API. Esta guía no requiere un IDE ni un complemento específico para software de arquitectura.

Para el ejemplo de llamadas a funciones, la aplicación debe contar con un servicio o una función invocable. Podría ser, por ejemplo, un servicio interno que devuelva los registros de espacios de un proyecto. El modelo genera la definición de la función y sus parámetros; realizar la llamada al servicio, procesar el resultado y, si corresponde, presentarlo al usuario siguen siendo responsabilidades del flujo de la aplicación.

Paso a paso: llamadas a funciones

1. Define la función. Especifica su nombre, descripción y esquema de parámetros. El siguiente ejemplo muestra una definición de función que la aplicación podría proporcionar para obtener los datos de los espacios de un proyecto. project_id se indica como un parámetro de texto y debe definirse de forma que coincida con los requisitos del servicio real.

from google import genai

get_room_data_function = {
    "type": "function",
    "name": "get_room_data",
    "description": "Returns room data for a project.",
    "parameters": {
        "type": "object",
        "properties": {
            "project_id": {"type": "string"}
        },
        "required": ["project_id"]
    }
}

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Mimari projedeki mekân verilerini getir.",
    tools=[{"type": "function", **get_room_data_function}]
)

for step in interaction.steps:
    if step.type == "function_call":
        print(step.name)
        print(step.arguments)

Este ejemplo muestra cómo leer el nombre de la función y sus argumentos en el paso de llamada a la función del modelo. No incluye el código que conecta con el servicio de datos de la aplicación: la definición de la función, por sí sola, no obtiene los datos de los espacios. La aplicación debe atender la llamada devuelta mediante su propio servicio, validar los parámetros y gestionar el resultado dentro de su flujo.

1. Limita el alcance de la función. Debe quedar claro qué hace y qué parámetros requiere. En un flujo de trabajo arquitectónico, leer una lista de espacios y modificar un registro del proyecto son operaciones diferentes; definirlas por separado ayuda a precisar qué acción debe ejecutar la aplicación. En sistemas reales, diseña también los pasos de validación y aprobación de la aplicación para las operaciones que puedan modificar datos o producir efectos externos.

2. Gestiona el paso de llamada desde la aplicación. Los ejemplos oficiales muestran cómo buscar los pasos de tipo function_call entre las etapas de la interacción y leer el nombre de la función y sus argumentos. El siguiente paso debería ser ejecutar la función correspondiente de la aplicación y procesar el resultado. Que el modelo genere una llamada a una función no significa que el servicio externo se haya ejecutado correctamente; la gestión de errores y la comprobación del resultado forman parte de la integración del servicio.

Paso a paso: salida estructurada

1. Determina los campos de datos necesarios. Por ejemplo, para extraer de una nota de proyecto el nombre de un espacio, su superficie y una lista de requisitos, puedes crear un esquema con tipos de objeto, matriz, texto y número entero. Elige los tipos de campo según cómo vaya a utilizar la aplicación esos datos. Además de JSON Schema, la fuente explica opciones para definir esquemas con Pydantic en Python y Zod en JavaScript.

2. Añade el esquema a la solicitud. El siguiente ejemplo de Python muestra cómo solicitar una respuesta en JSON y obtenerla del campo output_text. Los nombres de los campos son un ejemplo didáctico orientado a la arquitectura; la información que se extraiga de los documentos del proyecto debe definirse según los requisitos del trabajo.

from google import genai

client = genai.Client()
room_schema = {
    "type": "object",
    "properties": {
        "rooms": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "room_name": {"type": "string"},
                    "area_m2": {"type": "integer"},
                    "requirements": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                },
                "required": ["room_name", "area_m2", "requirements"]
            }
        }
    },
    "required": ["rooms"]
}

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Proje notundaki mekânları çıkar: giriş holü 12 m²; doğal ışık gereksinimi var.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": room_schema
    }
)

print(interaction.output_text)

El esquema define los campos de la respuesta y los tipos de datos esperados, pero no convierte en información verificada aquello que no figure en la nota del proyecto. Por ejemplo, si el texto no indica la superficie, la aplicación debe verificarla por separado o gestionar la falta de ese dato en su propio modelo de datos. También es importante definir los campos obligatorios de modo que sea razonable esperar que aparezcan en los textos fuente.

1. Valida el resultado en la aplicación. La salida estructurada está diseñada para facilitar el análisis de los datos; no garantiza la exactitud de las decisiones arquitectónicas. Compara la salida del modelo con la documentación del proyecto, los planos acotados o los registros autorizados. En especial, no transfieras sin aprobación a los planos ni a la base de datos del proyecto información con consecuencias importantes, como superficies, personas, fechas y requisitos técnicos.

Errores frecuentes

Un error fundamental es interpretar que el modelo ejecuta por sí solo el sistema externo cuando se llama a una función. El modelo puede proporcionar el nombre de la llamada y sus parámetros, pero la aplicación debe asociarla con el servicio adecuado y ejecutarla. Dejar ambiguos los nombres de las funciones, escribir descripciones demasiado generales u omitir en el esquema los parámetros necesarios también dificulta la integración.

En cuanto a la salida estructurada, recuerda que ajustarse al esquema no significa que toda la información del contenido sea correcta. Además, definir campos obligatorios sin tener en cuenta si aparecen en el texto fuente puede dar lugar a registros incompletos o inutilizables. Considera la salida del modelo como una etapa de datos estructurados, no como el resultado final y verificado del flujo de trabajo.

Próximos pasos en flujos de trabajo de arquitectura y archviz

Los estudios pueden evaluar estos enfoques en procesos que requieren separar las notas del proyecto en campos específicos o consultar datos de herramientas internas. También pueden servir a los estudiantes para aprender a extraer datos estructurados de textos y comprender los fundamentos de la integración con API. Sin embargo, estas funciones no se presentan en las fuentes como complementos que se conecten directamente con un software BIM, CAD o de visualización específico; la aplicación debe crear esa conexión por separado.

En la primera prueba, utiliza una función de solo lectura y alcance limitado, junto con un esquema fácil de verificar. Primero revisa cómo se extraen los campos de unas pocas notas de proyecto y, después, compara los resultados con las fuentes. Antes de pasar a una herramienta que se vaya a compartir en el estudio, aclara el acceso a la API y los posibles costes de uso, a qué servicio se enviarán los datos del proyecto y si la solución es compatible con la infraestructura de software actual. Como las fuentes no detallan estos aspectos, deben evaluarse según cada organización y la aplicación elegida.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de la documentación de Google para Gemini API “Function calling with the Gemini API” y “Structured outputs”. Ambas fuentes tienen licencia CC BY 4.0. Los ejemplos orientados a la arquitectura se han preparado específicamente para esta guía.