Implantar o agente do LangChain no Cloud Run

1. Visão geral

Um agente é um programa autônomo que conversa com um modelo de IA para realizar uma operação baseada em metas usando as ferramentas e o contexto disponíveis. Ele também é capaz de tomar decisões autônomas com base na verdade.

Frameworks de agentes, como o Kit de Desenvolvimento de Agente(ADK), o LangChain e o smolagents, são usados para criar agentes. Os aplicativos de agente criados com esses frameworks podem ser implantados no Cloud Run e disponibilizados aos usuários como aplicativos sem servidor.

Neste codelab, vamos criar um agente usando o LangChain e implantá-lo no Cloud Run.

O que você vai criar

Tudo pronto para passar do protótipo PROMPT para a criação de um agente? Vamos criar um agente usando o LangChain para receber informações sobre uma figura histórica em um formato estruturado. Neste laboratório, você vai:

1. Criar um agente simples para gerar informações sobre a figura histórica em um formato estruturado usando o LangChain
2. Execute o agente localmente e verifique se ele está funcionando conforme o esperado.
3. Implante o agente no Cloud Run e invoque-o usando o URL do Cloud Run.

Requisitos

• Um navegador, como o Chrome ou o Firefox
• Ter um projeto do Google Cloud com o faturamento ativado.

2. Antes de começar

Criar um projeto

1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.
3. Clique neste link para ativar o Cloud Shell. É possível alternar entre o terminal do Cloud Shell (para executar comandos da nuvem) e o editor (para criar projetos) clicando no botão correspondente no Cloud Shell.
4. Depois de se conectar ao Cloud Shell, verifique se sua conta já está autenticada e se o projeto está configurado com o ID do seu projeto usando o seguinte comando:

gcloud auth list

5. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto.

gcloud config list project

6. Se o projeto não estiver definido, use este comando:

gcloud config set project <YOUR_PROJECT_ID>

7. Verifique se você tem o Python 3.13 ou uma versão mais recente.

Consulte a documentação para outros comandos e usos do gcloud.

3. Como criar um agente LangChain

Estrutura do projeto

No Cloud Shell, crie uma pasta chamada langchain-app e adicione os seguintes arquivos nela:

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

Código do aplicativo

Estas são as dependências que você precisa adicionar ao requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

Em main.py, vamos escrever o código do agente que usa o modelo do Gemini e recupera as informações sobre a figura histórica. Depois de recuperados, eles são formatados em um formato estruturado conforme indicado.

Essa implementação usa a sintaxe moderna da 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. Testar o agente

Antes de implantar, é possível testar localmente.

1. Crie uma chave da API Gemini no AI Studio.
2. Exporte a chave da API Gemini como:

export GOOGLE_API_KEY="AIzaSy..."

3. Execute o servidor.

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

4. Teste o agente usando o seguinte comando curl:

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

Verifique se você está recebendo uma saída estruturada em JSON contendo o nome, a data de nascimento e o país de nascimento.

5. Implantar no Cloud Run

Vamos usar o comando gcloud run deploy para implantar o aplicativo do agente no Cloud Run. O comando a seguir cria o contêiner usando o Cloud Build e o implanta no Cloud Run em uma etapa.

Substitua YOUR_API_KEY pela sua chave de API Gemini.

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

Observação:para produção, é recomendável usar o Google Secret Manager para processar a chave de API em vez de variáveis de ambiente simples.

Depois da implantação, o endpoint vai aparecer no terminal e estará pronto para uso.

6. Testar a implantação

Use o endpoint do Cloud Run e execute o curl para garantir que você receba os resultados esperados.

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

Você vai receber o mesmo resultado que teve no aplicativo executado localmente.

7. Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste codelab, siga estas etapas:

1. No console do Google Cloud, acesse a página Gerenciar recursos.
2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir.
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

8. Parabéns

Parabéns! Você criou e interagiu com seu agente do LangChain implantado no Cloud Run.