פריסת סוכן LangChain ב-Cloud Run

1. סקירה כללית

סוכן הוא תוכנה אוטונומית שמתקשרת עם מודל AI כדי לבצע פעולה שמבוססת על מטרה, באמצעות הכלים וההקשר שיש לה, והיא מסוגלת לקבל החלטות אוטונומיות שמבוססות על עובדות!

משתמשים במסגרות של סוכנים כמו Agent Development Kit‏(ADK),‏ LangChain ו-smolagents כדי ליצור סוכנים. אפשר לפרוס את אפליקציות הסוכנים שנוצרו באמצעות מסגרות כאלה ב-Cloud Run, ולהפוך אותן לזמינות למשתמשים כאפליקציות ללא שרת.

ב-Codelab הזה נלמד איך ליצור סוכן באמצעות LangChain ולפרוס אותו ב-Cloud Run.

מה תפַתחו

מוכנים לעבור מהנחיית אב טיפוס ליצירת סוכן??? אנחנו ניצור סוכן באמצעות LangChain כדי לקבל מידע על דמות היסטורית בפורמט מובנה. במסגרת ה-Lab הזה:

  1. יצירת סוכן פשוט שיפיק מידע על דמות היסטורית בפורמט מובנה באמצעות LangChain
  2. מריצים את הסוכן באופן מקומי ומוודאים שהוא פועל כצפוי
  3. פריסת הסוכן ב-Cloud Run והפעלתו באמצעות כתובת URL של Cloud Run

דרישות

  • דפדפן, כמו Chrome או Firefox
  • פרויקט ב-Google Cloud שהחיוב בו מופעל.

‫2. לפני שמתחילים

יצירת פרויקט

  1. ב-מסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
  2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
  3. לוחצים על הקישור כדי להפעיל את Cloud Shell. אפשר לעבור בין Cloud Shell Terminal (כדי להפעיל פקודות בענן) לבין Editor (כדי ליצור פרויקטים) בלחיצה על הכפתור המתאים ב-Cloud Shell.
  4. אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהפרויקט מוגדר למזהה הפרויקט באמצעות הפקודה הבאה:
gcloud auth list
  1. מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.
gcloud config list project
  1. אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:
gcloud config set project <YOUR_PROJECT_ID>
  1. חשוב לוודא שמותקנת גרסה Python 3.13 ואילך

אפשר לעיין במאמרי העזרה בנושא פקודות gcloud ושימוש בהן.

3. יצירת סוכן LangChain

מבנה הפרויקט

ב-Cloud Shell, יוצרים תיקייה בשם langchain-app ומוסיפים אליה את הקבצים הבאים:

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

קוד אפליקציה

אלה יחסי התלות שצריך להוסיף בקובץ requirements.txt:

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

ב-main.py, נכתוב את קוד הסוכן שמשתמש במודל Gemini ומאחזר את המידע על הדמות ההיסטורית. אחרי השליפה, המידע מעוצב לפורמט מובנה לפי ההנחיות.

ההטמעה הזו משתמשת בתחביר המודרני של 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. בדיקת הנציג

לפני הפריסה, אפשר לבדוק אותו באופן מקומי.

  1. יוצרים מפתח Gemini API ב-AI Studio.
  2. מייצאים את מפתח Gemini API בתור:
export GOOGLE_API_KEY="AIzaSy..."
  1. מפעילים את השרת.
uvicorn main:app --port 8080 --host 0.0.0.0
  1. בודקים את הסוכן באמצעות הפקודה curl הבאה:
curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

בודקים שמקבלים פלט מובנה של JSON שמכיל את השם, תאריך הלידה ומדינת הלידה.

5. פריסה ב-Cloud Run

נשתמש בפקודה gcloud run deploy כדי לפרוס את אפליקציית הסוכן ב-Cloud Run. הפקודה הבאה יוצרת את הקונטיינר באמצעות Cloud Build ופורסת אותו ב-Cloud Run בשלב אחד.

מחליפים את הערך YOUR_API_KEY במפתח Gemini API בפועל.

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

אחרי הפריסה, נקודת הקצה אמורה להופיע במסוף ויהיה אפשר להשתמש בה.

6. בדיקת הפריסה

משתמשים בנקודת הקצה של Cloud Run ומבצעים את הפעולה curl כדי לוודא שמתקבלות התוצאות הצפויות.

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

התוצאה שמתקבלת צריכה להיות זהה לתוצאה שהתקבלה בהרצת האפליקציה באופן מקומי.

7. הסרת המשאבים

כדי לא לצבור חיובים לחשבון Google Cloud על המשאבים שבהם השתמשתם ב-Code Lab הזה:

  1. במסוף Google Cloud, עוברים לדף Manage resources.
  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

8. מזל טוב

מעולה! יצרתם אינטראקציה עם סוכן LangChain שפרסתם ב-Cloud Run.