Implementa el agente de LangChain en Cloud Run

1. Descripción general

Un agente es un programa autónomo que habla con un modelo de IA para realizar una operación basada en objetivos con las herramientas y el contexto que tiene, y es capaz de tomar decisiones autónomas basadas en la verdad.

Se utilizan frameworks de agentes, como Agent Development Kit(ADK), LangChain y Smolagents, para crear agentes. Las aplicaciones de agentes creadas a través de estos frameworks se pueden implementar en Cloud Run y estar disponibles para los usuarios como aplicaciones sin servidores.

En este codelab, compilaremos un agente con LangChain y lo implementaremos en Cloud Run.

Qué compilarás

¿Todo listo para pasar del PROMPT de prototipo a la creación de un agente? Crearemos un agente con LangChain para obtener información sobre una figura histórica en un formato estructurado. Como parte de este lab, harás lo siguiente:

1. Compila un agente simple para generar información sobre la figura histórica en un formato estructurado con LangChain
2. Ejecuta el agente de forma local y asegúrate de que funcione según lo esperado.
3. Implementa el agente en Cloud Run y lo invoca con la URL de Cloud Run

Requisitos

• Un navegador, como Chrome o Firefox
• Un proyecto de Google Cloud con facturación habilitada.

2. Antes de comenzar

Crea un proyecto

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información para verificar si la facturación está habilitada en un proyecto.
3. Haz clic en este vínculo para activar Cloud Shell. Para alternar entre la terminal de Cloud Shell (para ejecutar comandos de Cloud) y el editor (para compilar proyectos), haz clic en el botón correspondiente de Cloud Shell.
4. Una vez que te conectes a Cloud Shell, verifica que ya te autenticaste y que el proyecto se configuró con tu ID del proyecto usando el siguiente comando:

gcloud auth list

5. En Cloud Shell, ejecuta el siguiente comando para confirmar que el comando gcloud conoce tu proyecto.

gcloud config list project

6. Si tu proyecto no está configurado, usa el siguiente comando para hacerlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Asegúrate de tener Python 3.13 o una versión posterior.

Consulta la documentación para ver otros comandos y usos de gcloud.

3. Creación del agente de LangChain

Estructura del proyecto

En Cloud Shell, crea una carpeta llamada langchain-app y agrégale los siguientes archivos:

langchain-gemini-fastapi-app/
├── main.py
├── requirements.txt

Código de la aplicación

Estas son las dependencias que debes agregar en requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

En main.py, escribiremos el código del agente que usa el modelo de Gemini y recupera la información sobre la figura histórica. Una vez recuperada, la formatea en un formato estructurado según las indicaciones.

Esta implementación usa la sintaxis moderna de LCEL (LangChain Expression Language).

import os
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import JsonOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain App for Historical Figures")

# 1. Setup Gemini Model
# We expect GOOGLE_API_KEY to be set in the environment variables
llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    temperature=0.7
)

# 2. Define the Prompt
prompt = ChatPromptTemplate.from_template("You are an expert Historian. For the historical personality {name}, you are able to accurately tell their birth date and birth country. Return the output in the JSON format containing name, birthDate, birthCountry. In case you are unable to retrieve birthDate or birthCountry, just have the unknown values as null. ensure the response is a valid json object only.")
output_parser = JsonOutputParser()

# Chain: Prompt -> Model -> Json Output Parser
chain = prompt | llm | output_parser

# 3. Define Request Model
class QueryRequest(BaseModel):
    name: str

# 4. Define Endpoint
@app.post("/chat")
async def chat(request: QueryRequest):
    try:
        response = await chain.ainvoke({"name": request.name})
        return response
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/")
def health_check():
    return {"status": "ok", "service": "LangChain-Gemini-FastAPI"}

4. Prueba el agente

Antes de implementarla, puedes probarla de forma local.

1. Crea una clave de API de Gemini en AI Studio.
2. Exporta la clave de API de Gemini de la siguiente manera:

export GOOGLE_API_KEY="AIzaSy..."

3. Ejecuta el servidor.

uvicorn main:app --port 8080 --host 0.0.0.0

4. Prueba el agente con el siguiente comando de curl:

curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

Verifica que obtengas un resultado estructurado en formato JSON que contenga el nombre, la fecha de nacimiento y el país de nacimiento.

5. Implementa en Cloud Run

Usaremos el comando gcloud run deploy para implementar la aplicación del agente en Cloud Run. El siguiente comando compila el contenedor con Cloud Build y lo implementa en Cloud Run en un solo paso.

Reemplaza YOUR_API_KEY por tu clave de API de Gemini real.

gcloud run deploy gemini-fastapi-service \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_API_KEY=<YOUR_API_KEY>

Nota: Para la producción, se recomienda usar Google Secret Manager para controlar la clave de API en lugar de variables de entorno simples.

Una vez que se implemente, deberías ver tu extremo en la terminal, que estará listo para que lo uses.

6. Prueba la implementación

Usa el extremo de Cloud Run y realiza la acción curl para asegurarte de obtener los resultados esperados.

curl -X POST <CLOUD_RUN_ENDPOINT> \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

Deberías obtener el mismo resultado que obtuviste en la aplicación que se ejecuta de forma local.

7. Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab:

1. En la consola de Google Cloud, ve a la página Administrar recursos.
2. En la lista de proyectos, elige el proyecto que deseas borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrarlo.

8. Felicitaciones

¡Felicitaciones! Creaste correctamente tu agente de LangChain implementado en Cloud Run y pudiste interactuar con él.