Gemini API function calling: llamadas a herramientas en flujos de trabajo arquitectónicos

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

Gemini API function calling permite que un modelo, en lugar de limitarse a generar texto como respuesta, seleccione una función que pueda utilizarse en sistemas externos y prepare los parámetros necesarios para esa función. Quien la ejecuta realmente no es el modelo, sino la aplicación que conecta el modelo con el sistema externo. La guía de Google explica este enfoque para realizar operaciones en sistemas externos, obtener información de fuentes como API o bases de datos y ampliar las capacidades mediante herramientas de cálculo, entre otros usos.

Para los equipos de arquitectura, diseño de interiores y visualización, esta estructura puede servir como base para diseñar una aplicación que, por ejemplo, busque en un catálogo de materiales u obtenga información de un proyecto. El ejemplo siguiente muestra cómo el modelo prepara los parámetros que enviará a una función de búsqueda en un catálogo. La conexión al catálogo real y el uso de los resultados dependen del desarrollo de la aplicación.

Requisitos

Para empezar, se necesita una clave de Gemini API y un entorno capaz de enviar solicitudes a la API. La guía oficial de inicio muestra el uso del SDK de Python, el SDK de JavaScript y REST; también ofrece ejemplos para Java y Go. En esta explicación se utiliza Python.

Google AI Studio crea automáticamente un proyecto y una clave de API para los nuevos usuarios. La clave puede obtenerse en la página API keys de AI Studio. La guía explica cómo configurarla como variable de entorno. La clave de API sirve para vincular la solicitud a la cuenta y hacer un seguimiento del uso desde ella; también contribuye a aplicar límites de seguridad a las solicitudes.

Al pasar al uso de pago, se habilitan límites de solicitudes más amplios para la cuenta; en esta etapa es necesario configurar Cloud Billing. La guía de Google indica un prepago mínimo de 5 dólares estadounidenses o su equivalente en otra moneda para los créditos de pago. Esta información no es una estimación del costo de uso, sino la condición de prepago indicada en la fuente. Antes de pasar al uso de pago, revisa la configuración de la cuenta y de facturación.

El comando de la guía oficial para instalar el SDK de Python es:

pip install -U google-genai

Cómo crear una llamada a función paso a paso

1. Define el propósito de la función. El nombre y la descripción deben expresar claramente qué hace la aplicación. En este ejemplo, el objetivo es buscar opciones de materiales adecuadas para un proyecto en un catálogo externo. Aquí no se ejecuta la consulta en el catálogo; se muestra cómo el modelo genera los argumentos necesarios para realizarla.

2. Define la información que se solicitará al modelo. Por ejemplo, la solicitud del usuario podría ser:

Projem için açık renkli, taş görünümlü zemin kaplamalarını malzeme kataloğunda ara.

Este texto sirve como ejemplo de cómo el modelo convierte una solicitud en lenguaje natural en parámetros de una función. Los campos necesarios en la aplicación deben definirse según la estructura del catálogo; en el ejemplo siguiente, la consulta se guarda en un único campo de texto.

1. Prepara el esquema de la función. Los ejemplos de function calling de Google definen el nombre, la descripción y el esquema de parámetros de la función. Se especifica el tipo de los parámetros y los campos obligatorios se añaden a la lista required. search_materials y el campo query son ejemplos adaptados a un catálogo arquitectónico.

from google import genai

search_materials_function = {
    "type": "function",
    "name": "search_materials",
    "description": "Searches a project material catalog using a text query.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The material search query."
            }
        },
        "required": ["query"]
    }
}

Redacta la descripción de modo que explique la tarea real de la función. Elige también nombres de parámetros que coincidan con los campos que espera la aplicación conectada. Si un catálogo requiere varios filtros, el esquema debe diseñarse en consecuencia; sin embargo, los campos y filtros deben basarse en información que realmente exista en el sistema.

1. Envía la solicitud a Gemini API y revisa el paso de llamada. Los ejemplos de la guía de inicio utilizan el cliente genai.Client(), la solicitud interactions.create y campos de resultado como interaction.output_text. El documento sobre function calling muestra cómo comprobar si el tipo de paso de respuesta es function_call y leer el nombre de la función y sus argumentos.

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Projem için açık renkli, taş görünümlü zemin kaplamalarını ara.",
    tools=[search_materials_function],
)

for step in interaction.steps:
    if step.type == "function_call":
        print("İşlev:", step.name)
        print("Argümanlar:", step.arguments)

En este ejemplo, se espera que el modelo devuelva el nombre de la llamada a función y sus argumentos. Revisa en la aplicación los argumentos preparados por el modelo. El acceso al catálogo, la ejecución de la consulta y la presentación de los resultados al usuario son pasos de la aplicación que quedan fuera de este ejemplo.

1. Prueba las entradas antes de usar la función en producción. Observa qué función selecciona el modelo y qué argumentos genera ante distintas solicitudes de proyecto. En los casos en que la solicitud sea ambigua, diseña en tu propio sistema los controles necesarios para que la aplicación funcione de forma segura y correcta. Las guías de referencia explican el uso de la API y los pasos de llamada; no garantizan la exactitud ni la calidad de los datos de un catálogo arquitectónico específico.

Errores frecuentes

• Dejar poco clara la descripción de la función: La tarea de la herramienta que se espera que el modelo seleccione debe explicarse con claridad. El nombre, la descripción y las definiciones de los parámetros deben ser coherentes entre sí.

• No hacer coincidir los parámetros con la aplicación: Los campos del esquema deben corresponder a la información que espera el sistema externo. De lo contrario, aunque el modelo genere argumentos, es posible que la aplicación no pueda utilizarlos correctamente.

• Confundir la llamada del modelo con la ejecución de la operación: Function calling genera llamadas y argumentos para comunicarse con un sistema externo. La ejecución real de la función en el sistema depende de la conexión implementada en la aplicación.

• Gestionar la clave de API sin cuidado: La clave ayuda a vincular las solicitudes a una cuenta y a hacer un seguimiento del uso. La guía de inicio muestra cómo guardarla en una variable de entorno.

• Pasar por alto los costos y los límites de uso: Al pasar al nivel de pago, cambian los límites de solicitudes y la configuración de facturación. Antes de empezar a usarlo, revisa la información de uso y facturación en AI Studio.

Efectos en los flujos de trabajo de arquitectura y visualización

Este enfoque puede resultar útil para los equipos que quieran dirigir solicitudes en lenguaje natural a las herramientas definidas por una aplicación. Por ejemplo, en un proyecto de interiorismo se podría buscar que el modelo convierta una solicitud de búsqueda de materiales en una consulta estructurada para un catálogo. La recuperación de información de una API o base de datos externa también figura entre los usos mencionados en la fuente. Esto no significa que exista una conexión lista para usar con Revit, 3ds Max u otro software de diseño; es necesario implementar la integración.

Para los estudios y estudiantes, los aspectos importantes son la clave de API, la compatibilidad de la aplicación con el sistema externo, los límites de solicitudes y las posibles condiciones de uso de pago. Las fuentes no especifican requisitos especiales de hardware. Por eso, al tomar una decisión, es más adecuado evaluar el uso de la API y qué datos se exportarán en el flujo de trabajo, en lugar de hacer suposiciones sobre el hardware.

Próximos pasos

Primero, configura el esquema de una función acotada, como la búsqueda en un catálogo, y comprueba los argumentos que devuelve con solicitudes de ejemplo. Después, identifica una API o fuente de datos externa que pueda recibir esos argumentos desde la aplicación. Si prefieres otro lenguaje, también puedes consultar los ejemplos oficiales de JavaScript o REST de la guía de inicio. Para conversaciones de varios pasos, la guía presenta el enfoque previous_interaction_id, en el que el servidor gestiona el historial, como método recomendado para administrar el estado.

Fuentes y licencia

Esta guía se ha adaptado a partir de las guías de Google sobre Gemini API function calling y de inicio. Ambas fuentes tienen licencia CC BY 4.0. El contenido se tradujo al turco y se adaptó al caso de uso de un catálogo de materiales arquitectónicos.