Esegui il deployment di LangChain Agent su Cloud Run

1. Panoramica

Un agente è un programma autonomo che comunica con un modello di AI per eseguire un'operazione basata su un obiettivo utilizzando gli strumenti e il contesto a sua disposizione ed è in grado di prendere decisioni autonome basate sulla verità.

Per creare gli agenti vengono utilizzati framework come Agent Development Kit(ADK), LangChain e smolagents. Le applicazioni agent create tramite questi framework possono essere implementate su Cloud Run e rese disponibili agli utenti come applicazioni serverless.

In questo codelab, creeremo un agente utilizzando LangChain e lo eseguiremo il deployment su Cloud Run.

Cosa creerai

Vuoi passare dal PROMPT del prototipo alla creazione di un agente? Creeremo un agente utilizzando LangChain per ottenere informazioni su una figura storica in un formato strutturato. Nell'ambito di questo lab, imparerai a:

1. Crea un agente semplice per generare informazioni sul personaggio storico in un formato strutturato utilizzando LangChain
2. Esegui l'agente localmente e assicurati che funzioni come previsto.
3. Esegui il deployment dell'agente in Cloud Run e richiamalo utilizzando l'URL Cloud Run

Requisiti

• Un browser, ad esempio Chrome o Firefox
• Un progetto Google Cloud con la fatturazione abilitata.

2. Prima di iniziare

Crea un progetto

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.
3. Attiva Cloud Shell facendo clic su questo link. Puoi passare dal terminale Cloud Shell (per eseguire comandi cloud) all'editor (per creare progetti) facendo clic sul pulsante corrispondente in Cloud Shell.
4. Una volta eseguita la connessione a Cloud Shell, verifica di essere già autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

5. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

6. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Assicurati di avere Python 3.13 o versioni successive

Per altri comandi gcloud e informazioni sull'utilizzo, consulta la documentazione.

3. Creazione dell'agente LangChain

Struttura del progetto

In Cloud Shell, crea una cartella denominata langchain-app e aggiungi i seguenti file al suo interno:

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

Codice dell'applicazione

Ecco le seguenti dipendenze che devi aggiungere in requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

In main.py scriveremo il codice dell'agente che utilizza il modello Gemini e recupera le informazioni sul personaggio storico. Una volta recuperato, lo formatta in un formato strutturato come indicato.

Questa implementazione utilizza la sintassi moderna 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. Testare l'agente

Prima del deployment, puoi testarlo localmente.

1. Crea una chiave API Gemini in AI Studio.
2. Esporta la chiave API Gemini come:

export GOOGLE_API_KEY="AIzaSy..."

3. Esegui il server.

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

4. Testa l'agente utilizzando il seguente comando curl:

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

Verifica di ricevere un output strutturato in formato JSON contenente nome, data di nascita e paese di nascita.

5. Esegui il deployment in Cloud Run

Utilizzeremo il comando gcloud run deploy per eseguire il deployment dell'applicazione agente in Cloud Run. Il comando seguente crea il container utilizzando Cloud Build e ne esegue il deployment su Cloud Run in un unico passaggio.

Sostituisci YOUR_API_KEY con la tua chiave API Gemini effettiva.

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

Nota:per la produzione, è consigliabile utilizzare Google Secret Manager per gestire la chiave API anziché variabili di ambiente semplici.

Una volta eseguito il deployment, dovresti vedere l'endpoint nel terminale, pronto per l'uso.

6. Testare il deployment

Utilizza l'endpoint Cloud Run ed esegui curl per assicurarti di ottenere i risultati previsti.

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

Dovresti ottenere lo stesso risultato che avevi ottenuto nell'applicazione in esecuzione in locale.

7. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, segui questi passaggi:

1. Nella console Google Cloud, vai alla pagina Gestisci risorse.
2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

8. Complimenti

Complimenti! Hai creato e interagito correttamente con il tuo agente LangChain di cui è stato eseguito il deployment su Cloud Run.