Como Construir Agentes de IA con Function Calling de Gemma 4

Gemma 4 viene con soporte nativo para llamada de funciones, lo que significa que puedes construir agentes de IA que no solo generan texto — sino que toman acciones. Llamar APIs, consultar bases de datos, buscar en la web, ejecutar calculos. Esta guia te muestra como construir un agente funcional desde cero usando Gemma 4 y Python.

¿Que es Function Calling?

La llamada de funciones permite al modelo decidir cuando usar herramientas externas en lugar de adivinar una respuesta. En lugar de preguntarle a Gemma 4 "¿cual es el clima en Tokio?" y obtener una respuesta alucinada, el modelo genera una solicitud estructurada para llamar a tu API del clima, tu la ejecutas, le devuelves el resultado, y el modelo genera una respuesta en lenguaje natural basada en datos reales.

El flujo se ve asi:

Usuario: "What's the weather in Tokyo?"
  → Modelo: {"function": "get_weather", "args": {"city": "Tokyo"}}
  → Tu codigo llama a la API del clima → devuelve {"temp": 22, "condition": "sunny"}
  → Modelo: "It's 22°C and sunny in Tokyo right now."

Definiendo Herramientas con JSON Schema

Primero, necesitas decirle a Gemma 4 que herramientas estan disponibles. Cada herramienta se define con un esquema JSON que describe su nombre, proposito y parametros:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city. Use this when the user asks about weather conditions.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. 'Tokyo', 'New York'"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "Perform mathematical calculations. Use for any math the user asks about.",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "Math expression to evaluate, e.g. '2 + 2', 'sqrt(144)'"
                    }
                },
                "required": ["expression"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Search the web for current information. Use when the user asks about recent events or facts you're unsure about.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query"
                    },
                    "num_results": {
                        "type": "integer",
                        "description": "Number of results to return (default: 3)"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

Las buenas descripciones de herramientas son criticas. El modelo las usa para decidir que herramienta llamar y cuando. Se especifico sobre cuando debe usarse cada herramienta.

Construyendo el Bucle del Agente

Aqui tienes un agente Python completo que usa Gemma 4 a traves de la API de Ollama:

import json
import requests
import math

OLLAMA_URL = "http://localhost:11434/api/chat"
MODEL = "gemma4:12b"

# Define your tool implementations
def get_weather(city: str, unit: str = "celsius") -> dict:
    """Simulated weather API — replace with a real API call"""
    # In production, call OpenWeatherMap, WeatherAPI, etc.
    return {
        "city": city,
        "temperature": 22,
        "unit": unit,
        "condition": "sunny",
        "humidity": 45
    }

def calculate(expression: str) -> dict:
    """Safe math evaluation"""
    allowed_names = {
        "sqrt": math.sqrt,
        "sin": math.sin,
        "cos": math.cos,
        "pi": math.pi,
        "e": math.e,
        "abs": abs,
        "round": round
    }
    try:
        result = eval(expression, {"__builtins__": {}}, allowed_names)
        return {"expression": expression, "result": result}
    except Exception as e:
        return {"expression": expression, "error": str(e)}

def web_search(query: str, num_results: int = 3) -> dict:
    """Simulated web search — replace with real search API"""
    return {
        "query": query,
        "results": [
            {"title": f"Result about {query}", "snippet": "Relevant information..."}
        ]
    }

# Map function names to implementations
TOOL_MAP = {
    "get_weather": get_weather,
    "calculate": calculate,
    "web_search": web_search,
}

def call_gemma(messages: list, tools: list) -> dict:
    """Send a chat request to Gemma 4 via Ollama"""
    response = requests.post(OLLAMA_URL, json={
        "model": MODEL,
        "messages": messages,
        "tools": tools,
        "stream": False
    })
    return response.json()

def run_agent(user_input: str, tools: list, max_steps: int = 5):
    """Run the agent loop with multi-step tool use"""
    messages = [
        {
            "role": "system",
            "content": "You are a helpful assistant. Use the provided tools when needed. Always use tools for weather, calculations, and current information instead of guessing."
        },
        {"role": "user", "content": user_input}
    ]

    for step in range(max_steps):
        response = call_gemma(messages, tools)
        message = response["message"]

        # Check if the model wants to call a tool
        if "tool_calls" in message and message["tool_calls"]:
            # Process each tool call
            for tool_call in message["tool_calls"]:
                func_name = tool_call["function"]["name"]
                func_args = tool_call["function"]["arguments"]

                print(f"  → Calling {func_name}({func_args})")

                # Execute the tool
                if func_name in TOOL_MAP:
                    result = TOOL_MAP[func_name](**func_args)
                else:
                    result = {"error": f"Unknown tool: {func_name}"}

                # Add the tool call and result to messages
                messages.append(message)
                messages.append({
                    "role": "tool",
                    "content": json.dumps(result)
                })
        else:
            # Model gave a final text response
            print(f"Agent: {message['content']}")
            return message["content"]

    return "Agent reached maximum steps without completing."

# Run the agent
if __name__ == "__main__":
    run_agent("What's the weather in Tokyo and what's 15% of 8500?", tools)

Este agente puede manejar consultas de multiples pasos. Cuando preguntas "¿Cual es el clima en Tokio y cuanto es el 15% de 8500?", Gemma 4 llamara a get_weather y calculate por separado, luego combinara ambos resultados en una sola respuesta natural.

Patrones de Agente Multi-Paso

Los agentes reales a menudo necesitan encadenar multiples llamadas a herramientas donde las llamadas posteriores dependen de resultados anteriores:

# Example: "Find restaurants near me and check the weather there"
# Step 1: Model calls web_search("restaurants near me")
# Step 2: Model sees results, calls get_weather(city from results)
# Step 3: Model combines both into a recommendation

# The agent loop handles this naturally — each tool result
# gets added to the conversation, and the model decides
# what to do next based on the full history

Salida Estructurada para Uso Confiable de Herramientas

Gemma 4 soporta salida estructurada, lo que significa que puedes forzar al modelo a responder en un formato JSON especifico. Esto es util cuando necesitas la respuesta final del agente en una estructura legible por maquinas:

response = requests.post(OLLAMA_URL, json={
    "model": MODEL,
    "messages": messages,
    "format": {
        "type": "object",
        "properties": {
            "answer": {"type": "string"},
            "confidence": {"type": "number"},
            "sources": {
                "type": "array",
                "items": {"type": "string"}
            }
        },
        "required": ["answer", "confidence"]
    },
    "stream": False
})

Esto garantiza que la salida sea JSON valido que coincide con tu esquema — no mas parsear texto libre y esperar lo mejor.

Consejos para una Mejor Llamada de Funciones

Consejo	Por Que
Escribe descripciones detalladas de herramientas	El modelo se basa en las descripciones para elegir la herramienta correcta
Usa campos `required` en los esquemas	Evita que el modelo omita parametros criticos
Limita el conteo de herramientas a 5-10	Demasiadas herramientas confunden al modelo
Incluye ejemplos en las descripciones	"e.g., 'New York', 'London'" ayuda al modelo a formatear argumentos correctamente
Maneja errores con gracia	Devuelve informacion de error para que el modelo pueda reintentar o informar al usuario
Establece un limite de max_steps	Evita bucles infinitos si el modelo sigue llamando a herramientas

Errores Comunes

El modelo ignora las herramientas y responde directamente: Haz que tu prompt del sistema le diga explicitamente al modelo que use las herramientas. Agrega "NUNCA adivines el clima/matematicas/hechos — siempre usa las herramientas proporcionadas."

Tipos de argumento incorrectos: Si el modelo envia "3" en lugar de 3 para un parametro entero, agrega coercion de tipo en tus implementaciones de herramientas.

El modelo llama a herramientas innecesariamente: Se especifico en las descripciones de herramientas sobre cuando usarlas. "Usa SOLO cuando el usuario pregunte explicitamente sobre el clima" es mejor que "Obtener informacion del clima."

Siguientes Pasos

¿Quieres aprender los conceptos basicos de la API de Ollama primero? Consulta nuestro Tutorial de API de Gemma 4 para una introduccion mas gentil
¿Necesitas elegir el modelo correcto para cargas de trabajo de agentes? El modelo 12B es el punto dulce — ve ¿Cual Modelo de Gemma 4?
¿Construyendo agentes multimodales? Lee la Guia Multimodal para agregar capacidades de vision a tu agente

La llamada de funciones transforma a Gemma 4 de un chatbot a una herramienta real. Una vez que conectas APIs reales — clima, busqueda, bases de datos, email — tienes un agente de IA que puede tomar acciones significativas en el mundo real, todo ejecutandose localmente en tu propio hardware.

gemma4 — interact