פריסת סוכן

כשפורסים סוכן ב-Agent Runtime, הוא זמין מרחוק לטיפול בבקשות. במאמר הזה מוסבר איך לפרוס נציג בהתאם לתהליך הפיתוח שלכם: מאובייקט הפעלה, מקובצי מקור מקומיים, מקובץ Docker, מקובץ אימג' של קונטיינר שמתארח ב-Artifact Registry, ממאגר Git ציבורי או ישירות דרך מאגר Git מקושר.

כדי לפרוס נציג ב-Agent Runtime, בוחרים באחת מהשיטות הבאות:

Developer Connect

מומלץ לפרויקטים שמנוהלים במאגר Git שמקושר דרך Developer Connect. השיטה הזו מייעלת את פריסת הנציגים ישירות מקוד המקור, ותומכת באופן מובנה בניהול גרסאות, בשיתוף פעולה בצוות ובצינורות עיבוד נתונים של CI/CD. לפני שמשתמשים בשיטה הזו, צריך להגדיר את הקישור למאגר Git לפי ההוראות במאמר הגדרת קישור למאגר Git ב-Developer Connect.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

מאגר Git ציבורי

מתאים לפרויקטים במאגר Git ציבורי שאפשר לגשת אליו באמצעות HTTPS. השיטה הזו מאפשרת לפרוס ישירות מכתובת ה-URL של המאגר בלי להגדיר חיבור Developer Connect או קישור למאגר Git. השיטה הזו תומכת רק במאגרים ציבוריים. כדי לפרוס ממאגר פרטי, צריך להשתמש ב-Developer Connect.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

קובצי מקור

מתאים לתהליכי עבודה אוטומטיים כמו צינורות עיבוד נתונים של CI/CD וכלים של תשתית כקוד כמו Terraform, שמאפשרים פריסות אוטומטיות והצהרתיות לחלוטין. הוא פורס את הנציג ישירות מקוד המקור המקומי, ולא נדרשת קטגוריה של Cloud Storage.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

קובץ Docker

בדומה לפריסה מקובצי מקור. אתם פורסים את הנציג ישירות מקוד מקור מקומי, בלי צורך בקטגוריה של Cloud Storage. השיטה הזו מתאימה אם אתם צריכים להגדיר את שרת ה-API שנפרס ולשלוט בו. הקונטיינר שנפרס חייב לעמוד בדרישות של חוזה זמן הריצה.

אפשר להשתמש בשיטת הפריסה הזו בכל שפה.

קובץ אימג' של קונטיינר

בדומה לפריסה מקובץ Docker. אתם פורסים קובץ אימג' של קונטיינר שמתארח ב-Artifact Registry. כדאי להשתמש בשיטה הזו אם אתם צריכים שליטה על תהליך ה-build של קובץ האימג' של הקונטיינר וזמן אחזור קצר יותר בפריסה. קובץ האימג' של הקונטיינר חייב לעמוד בדרישות של חוזה זמן הריצה.

אפשר להשתמש בשיטת הפריסה הזו בכל שפה.

Agent Platform SDK

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

כדי להתחיל, מבצעים את השלבים הבאים:

  1. השלמת הדרישות המוקדמות
  2. אופציונלי: הגדרת הנציג לפריסה
  3. יצירת מכונה של Gemini Enterprise Agent Platform
  4. אופציונלי: קבלת מזהה המשאב של הנציג
  5. אופציונלי: רשימת הפעולות הנתמכות
  6. אופציונלי: מתן הרשאות לסוכן שנפרס

דרישות מוקדמות

לפני שפורסים נציג, צריך לבצע את המשימות הבאות:

  1. הגדרת הסביבה
  2. יצירת נציג

אופציונלי: הגדרת הסוכן לפריסה

אתם יכולים להגדיר הגדרות אופציונליות לנציג. הדוגמאות בקטע הזה הן ב-Python.

יצירת מופע של Agent Platform

בקטע הזה מוסבר איך ליצור מכונה של Agent Platform כדי לפרוס סוכן. אפשר לבחור בין השיטות הבאות:

Developer Connect

כדי לפרוס מ-Developer Connect ב-Agent Platform, משתמשים ב-client.runtimes.create ומספקים את developer_connect_source,‏ entrypoint_module ו-entrypoint_object במילון ההגדרות האישיות, יחד עם הגדרות אופציונליות אחרות. בשיטה הזו אפשר לפרוס קוד ישירות ממאגר Git מקושר.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

remote_agent = client.runtimes.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

הפרמטרים לפריסה של Developer Connect הם:

  • ‫developer_connect_source (dict): ההגדרות לאחזור קוד המקור. פרטים נוספים זמינים במאמר הגדרת קישור למאגר Git ב-Developer Connect.
    • ‫git_repository_link (str): שם המשאב של הקישור למאגר Git ב-Developer Connect.
    • ‫revision (str): הגרסה שצריך לאחזר (ענף, תג או SHA של commit).
    • ‫dir (str): תיקיית השורש של קוד הנציג במאגר.
  • ‫entrypoint_module (str): השם של מודול Python שמכיל את נקודת הכניסה של הסוכן, ביחס לספרייה שצוינה ב-developer_connect_source.dir.
  • ‫entrypoint_object (str): השם של האובייקט שניתן לקריאה בתוך entrypoint_module שמייצג את אפליקציית הנציג (לדוגמה, root_agent).
  • ‫requirements_file (str): אופציונלי: הנתיב לקובץ דרישות של pip ביחס לתיקיית קוד המקור. ברירת המחדל היא requirements.txt.

הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:

  1. שירות Agent Runtime מאחזר את קוד המקור מהגרסה שצוינה במאגר Git.
  2. השירות מתקין יחסי תלות מ-requirements_file (אם סופקו).
  3. השירות מפעיל את אפליקציית הנציג באמצעות entrypoint_module ו-entrypoint_object שצוינו.

זמן האחזור של הפריסה תלוי בזמן הכולל שלוקח להתקין את החבילות הנדרשות. אחרי הפריסה, remote_agent תואם למכונה של local_agent שפועלת ב-Agent Platform, ואפשר לשלוח אליה שאילתות או למחוק אותה.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

מאגר Git ציבורי

כדי לפרוס ממאגר Git ציבורי ב-Agent Platform, משתמשים ב-client.runtimes.create ומספקים את git_source,‏ entrypoint_module,‏ entrypoint_object ו-class_methods במילון ההגדרות האישיות, יחד עם הגדרות אישיות אופציונליות אחרות. כדי לפרוס ממאגר פרטי, משתמשים ב-Developer Connect.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

remote_agent = client.runtimes.create(
    config={
        "git_source": {                                 # Required.
            "url": "https://github.com/OWNER/REPO.git", # Required.
            "revision": "main",                         # Required.
            "dir": "path/to/dir",                       # Optional.
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

הפרמטרים לפריסה של מאגר Git ציבורי הם:

  • ‫git_source (dict): ההגדרה לאחזור קוד מקור ממאגר Git ציבורי.
    • url (str): כתובת ה-URL מסוג HTTPS של מאגר Git ציבורי (לדוגמה, https://github.com/OWNER/REPO.git). כתובת ה-URL לא יכולה להכיל פרטי כניסה, כמו user:password@.
    • ‫revision (str): ענף, תג או SHA מלא של commit לאחזור. אין תמיכה ב-SHA מקוצרים של commit.
    • ‫dir (str): אופציונלי: הספרייה שבה ה-build פועל, ביחס לשורש המאגר. רק התוכן של הספרייה הזו נפרס. אם לא מגדירים את המדיניות, המערכת תשתמש בתיקיית הבסיס של המאגר. הנתיב לא יכול להתחיל ב-/ או להכיל קטעי ...
  • ‫entrypoint_module (str): השם של מודול Python שמכיל את נקודת הכניסה של הסוכן, ביחס לספרייה שצוינה ב-git_source.dir.
  • ‫entrypoint_object (str): השם של האובייקט שניתן לקריאה בתוך entrypoint_module שמייצג את אפליקציית הנציג (לדוגמה, root_agent).
  • ‫class_methods (list[dict]): רשימה של מילונים שמגדירים את השיטות החשופות של הנציג. כל מילון כולל את השדות name, api_mode ואת השדה האופציונלי parameters. במאמר רשימת הפעולות הנתמכות מפורט מידע נוסף על השיטות של סוכן בהתאמה אישית.
  • ‫requirements_file (str): אופציונלי: הנתיב לקובץ דרישות pip ביחס ל-git_source.dir (או לשורש המאגר אם dir לא מוגדר). ברירת המחדל היא requirements.txt.

הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:

  1. שירות Agent Runtime משכפל את המאגר בגרסה שצוינה.
  2. השירות מתקין יחסי תלות מ-requirements_file (אם הקובץ קיים).
  3. השירות מפעיל את אפליקציית הנציג באמצעות entrypoint_module ו-entrypoint_object שצוינו.

זמן האחזור של הפריסה תלוי בזמן הכולל שלוקח להתקין את החבילות הנדרשות. אחרי הפריסה, remote_agent תואם לנציג שפועל ב-Agent Platform, ואפשר לשלוח אליו שאילתות או למחוק אותו.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

קובצי מקור

כדי לפרוס מקובצי מקור ב-Agent Platform, משתמשים ב-client.runtimes.create ומספקים את source_packages,‏ entrypoint_module,‏ entrypoint_object ו-class_methods במילון התצורה, יחד עם הגדרות אופציונליות אחרות. בשיטה הזו, לא צריך להעביר אובייקט של נציג או קטגוריה של Cloud Storage.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.runtimes.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

הפרמטרים לפריסת מקור מוטמע הם:

  • ‫source_packages (list[str]): רשימה של נתיבים מקומיים לקבצים או לספריות שצריך לכלול בפריסה. הגודל הכולל של הקבצים והספריות ב-source_packages לא יכול לחרוג מ-8MB.
  • ‫entrypoint_module (str): השם המלא של מודול Python שמכיל את נקודת הכניסה של הסוכן (לדוגמה, agent_dir.agent).
  • ‫entrypoint_object (str): השם של האובייקט שניתן לקריאה בתוך entrypoint_module שמייצג את אפליקציית הנציג (לדוגמה, root_agent).
  • ‫class_methods (list[dict]): רשימה של מילונים שמגדירים את השיטות החשופות של הנציג. כל מילון כולל את השדות name, api_mode ואת השדה האופציונלי parameters. במאמר רשימת הפעולות הנתמכות מפורט מידע נוסף על השיטות של סוכן בהתאמה אישית.

    לדוגמה:

    class_methods = [
        {
            "name": "method_name",
            "api_mode": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
            "parameters": {
                "type": "object",
                "properties": {
                    "param1": {"type": "string", "description": "Description of param1"},
                    "param2": {"type": "integer"}
                },
                "required": ["param1"]
            }
        }
    ]
  • ‫requirements_file (str): אופציונלי: הנתיב לקובץ דרישות pip בתוך הנתיבים שצוינו ב-source_packages. ברירת המחדל היא requirements.txt בתיקיית השורש של המקור הארוז.

הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:

  1. ה-SDK של Agent Platform יוצר ארכיון tar.gz של הנתיבים שצוינו ב-source_packages.
  2. הארכיון הזה מקודד ונשלח ישירות ל-Agent Platform API.
  3. שירות Agent Runtime מקבל את הארכיון, מחלץ אותו, מתקין יחסי תלות מ-requirements_file (אם סופקו) ומפעיל את אפליקציית הסוכן באמצעות entrypoint_module ו-entrypoint_object שצוינו.

זמן האחזור של הפריסה תלוי בזמן הכולל שלוקח להתקין את החבילות הנדרשות. אחרי הפריסה, remote_agent תואם למכונה של local_agent שפועלת ב-Agent Platform, ואפשר לשלוח אליה שאילתות או למחוק אותה.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

קובץ Docker

פריסה מקובץ Docker ב-Agent Platform דומה לפריסה מקובצי מקור, אבל צריך לכלול Dockerfile בקובצי המקור ולציין image_spec בהגדרות במקום entrypoint_module, entrypoint_object ו-requirements_file. הקונטיינר שנוצר מקובץ ה-Docker צריך להאזין לבקשות HTTP ב-0.0.0.0 ביציאה 8080 ולפעול בהתאם לחוזה של סביבת זמן הריצה.

אפשר להשתמש בשיטת הפריסה הזו בכל שפה.

קודם כל, יוצרים קובץ Dockerfile בתיקיית השורש של הפרויקט, שמתקין יחסי תלות ומפעיל את שרת ה-HTTP ב-0.0.0.0:8080:

Python

FROM python:3.13-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

# Start an ADK API server or custom FastAPI server on 0.0.0.0:8080:
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

המשך

FROM golang:1.24 AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /app/server .

FROM gcr.io/distroless/static-debian12
WORKDIR /app
COPY --from=builder /app/server /app/server

EXPOSE 8080

# For an ADK Go agent using the built-in launcher:
# CMD ["/app/server", "web", "-host", "0.0.0.0", "-port", "8080", "agentengine"]
# For a custom Go HTTP server listening on 0.0.0.0:8080:
CMD ["/app/server"]

TypeScript

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 8080

# For an ADK TypeScript agent (with @google/adk-devtools in package.json):
# CMD ["npx", "adk", "api_server", "/app/agents/my_agent", "--host=0.0.0.0", "--port=8080"]
# For a custom Node.js HTTP server listening on 0.0.0.0:8080:
CMD ["node", "dist/index.js"]

Java

FROM maven:3.9-eclipse-temurin-17
WORKDIR /app

COPY pom.xml .
COPY src ./src
RUN mvn package -DskipTests

EXPOSE 8080

# For an ADK Java agent using AdkWebServer (set --server.address=0.0.0.0):
# CMD ["sh", "-c", "mvn exec:java -Dexec.mainClass=com.google.adk.web.AdkWebServer -Dexec.args='--server.address=0.0.0.0 --server.port=${PORT:-8080} --adk.agents.source-dir=.'"]
# For a packaged Java HTTP server JAR listening on 0.0.0.0:8080:
CMD ["java", "-jar", "target/app.jar"]

אם הקונטיינר שלכם מטמיע את נקודות הקצה לניתוב של חוזה זמן הריצה (/api/reasoning_engine ו-/api/stream_reasoning_engine, שגם מרכז האפליקציות של ADK Go agentengine חושף), צריך להצהיר על הפעולות הנתמכות ב-class_methods (או ב-spec.classMethods ב-REST) כדי שתוכלו להפעיל את הנציג באמצעות בקשות query ו-streamQuery רגילות. אם הקונטיינר מריץ את שרת ה-API של ADK (כמו npx adk api_server ל-TypeScript או AdkWebServer ל-Java), צריך להפעיל את נקודות הקצה /run ו-/run_sse שלו דרך proxy ל-API הבסיסי (/api/run ו-/api/run_sse).

עכשיו פורסים את הנציג מקובצי המקור המקומיים ו-Dockerfile באמצעות Agent Platform SDK, ‏API בארכיטקטורת REST או Terraform:

Agent Platform SDK

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile
#
# For other languages, pass your project's source files and Dockerfile in source_packages:
#   Go:         ["main.go", "go.mod", "go.sum", "Dockerfile"]
#   TypeScript: ["src", "package.json", "package-lock.json", "tsconfig.json", "Dockerfile"]
#   Java:       ["src", "pom.xml", "Dockerfile"]

remote_agent = client.runtimes.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Optional: declare class_methods if your container implements /api/reasoning_engine or /api/stream_reasoning_engine
        # "class_methods": class_methods,
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

זמן האחזור של הפריסה תלוי בזמן הכולל שנדרש כדי ליצור את קובץ האימג' של הקונטיינר ולהתקין את החבילות הנדרשות. אחרי הפריסה, remote_agent תואם לנציג שפועל ב-Agent Platform, ואפשר לשלוח אליו שאילתות או למחוק אותו.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

REST

אורזים את קובץ ה-Dockerfile ואת קובצי המקור של האפליקציה ברמת הבסיס של ארכיון .tar.gz (עד 8MB), מקודדים את הארכיון ב-base64 ושולחים בקשת POST ל-method‏ reasoningEngines.create:

# Package your Dockerfile and source files at the root of a tar.gz archive
# (replace main.py and requirements.txt with your project's source files):
tar -czf /tmp/source.tar.gz Dockerfile main.py requirements.txt

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" \
  -d "{
    \"displayName\": \"Dockerfile agent\",
    \"spec\": {
      \"sourceCodeSpec\": {
        \"inlineSource\": {
          \"sourceArchive\": \"$(base64 < /tmp/source.tar.gz | tr -d '\n')\"
        },
        \"imageSpec\": {}
      }
    }
  }"

הבקשה מחזירה Operation ארוך-טווח שמתייחס למשאב ReasoningEngine שנפרס, אחרי שה-build והפריסה של הקונטיינר מסתיימים.

קובץ אימג' של קונטיינר

כדי לפרוס מקובץ אימג' של קונטיינר, קודם צריך לפעול לפי הוראות ההגדרה של Bring your own container כדי ליצור את קובץ האימג' ולהעביר אותו ל-Artifact Registry. אם אתם משתמשים ב-Agent Platform SDK כדי ליצור את המכונה של Agent Platform, ודאו שאתם מתקינים גרסה של google-cloud-aiplatform שתואמת ל->=1.144. קובץ האימג' של הקונטיינר צריך להאזין לבקשות HTTP ב-0.0.0.0 ביציאה 8080 ולעמוד בחוזה של סביבת זמן הריצה.

אפשר להשתמש בשיטת הפריסה הזו בכל שפה.

בדוגמאות הבאות מוצג Dockerfile ליצירת קובץ אימג' של קונטיינר שמאזין ל-0.0.0.0:8080:

Python

FROM python:3.13-slim
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

# Start an ADK API server or custom FastAPI server on 0.0.0.0:8080:
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

המשך

FROM golang:1.24 AS builder
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /app/server .

FROM gcr.io/distroless/static-debian12
WORKDIR /app
COPY --from=builder /app/server /app/server

EXPOSE 8080

# For an ADK Go agent using the built-in launcher:
# CMD ["/app/server", "web", "-host", "0.0.0.0", "-port", "8080", "agentengine"]
# For a custom Go HTTP server listening on 0.0.0.0:8080:
CMD ["/app/server"]

TypeScript

FROM node:22-slim
WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

EXPOSE 8080

# For an ADK TypeScript agent (with @google/adk-devtools in package.json):
# CMD ["npx", "adk", "api_server", "/app/agents/my_agent", "--host=0.0.0.0", "--port=8080"]
# For a custom Node.js HTTP server listening on 0.0.0.0:8080:
CMD ["node", "dist/index.js"]

Java

FROM maven:3.9-eclipse-temurin-17
WORKDIR /app

COPY pom.xml .
COPY src ./src
RUN mvn package -DskipTests

EXPOSE 8080

# For an ADK Java agent using AdkWebServer (set --server.address=0.0.0.0):
# CMD ["sh", "-c", "mvn exec:java -Dexec.mainClass=com.google.adk.web.AdkWebServer -Dexec.args='--server.address=0.0.0.0 --server.port=${PORT:-8080} --adk.agents.source-dir=.'"]
# For a packaged Java HTTP server JAR listening on 0.0.0.0:8080:
CMD ["java", "-jar", "target/app.jar"]

אם הקונטיינר שלכם מטמיע את נקודות הקצה לניתוב של חוזה זמן הריצה (/api/reasoning_engine ו-/api/stream_reasoning_engine, שגם מרכז האפליקציות של ADK Go agentengine חושף), צריך להצהיר על הפעולות הנתמכות ב-class_methods (או ב-spec.classMethods ב-REST) כדי שתוכלו להפעיל את הנציג באמצעות בקשות query ו-streamQuery רגילות. אם הקונטיינר מריץ את שרת ה-API של ADK (כמו npx adk api_server ל-TypeScript או AdkWebServer ל-Java), צריך להפעיל את נקודות הקצה /run ו-/run_sse שלו דרך proxy ל-API הבסיסי (/api/run ו-/api/run_sse).

אחרי שיוצרים את קובץ האימג' של הקונטיינר ודוחפים אותו ל-Artifact Registry, פורסים את הסוכן באמצעות Agent Platform SDK,‏ API בארכיטקטורת REST או Terraform:

Agent Platform SDK

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Optional: declare class_methods if your container implements /api/reasoning_engine or /api/stream_reasoning_engine
        # "class_methods": class_methods,
        # Other optional configs
        "display_name": "Container image agent",
    },
)

כאשר CONTAINER_IMAGE_URI תואם ל-URI של קובץ האימג' של הקונטיינר ב-Artifact Registry (למשל us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

אחרי הפריסה, remote_agent תואם לנציג שפועל ב-Agent Platform, ואפשר לשלוח אליו שאילתות או למחוק אותו.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

REST

שולחים בקשת POST ל-method‏ reasoningEngines.create:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" \
  -d '{
    "displayName": "Container image agent",
    "spec": {
      "containerSpec": {
        "imageUri": "CONTAINER_IMAGE_URI"
      }
    }
  }'

כאשר CONTAINER_IMAGE_URI תואם ל-URI של קובץ האימג' של הקונטיינר ב-Artifact Registry (למשל us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag). הבקשה מחזירה Operation ארוך-טווח שמתייחס למשאב ReasoningEngine שנפרס לאחר השלמת הפריסה.

Agent Platform SDK

כדי לפרוס את הסוכן ב-Agent Platform, משתמשים ב-client.runtimes.create כדי להעביר את האובייקט local_agent יחד עם הגדרות אופציונליות:

remote_agent = client.runtimes.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:

  1. חבילה של פריטי המידע שנוצרו באופן מקומי:
  2. החבילה מועלית ל-Cloud Storage (בתיקייה המתאימה) כדי להכין את פריטי המידע שנוצרו.
  3. מזהי ה-URI של Cloud Storage לפריטי המידע הרלוונטיים שנוצרו בתהליך הפיתוח (Artifacts) מצוינים ב-PackageSpec.
  4. שירות Agent Runtime מקבל את הבקשה, יוצר קונטיינרים ומפעיל שרתי HTTP בקצה העורפי.

זמן האחזור של הפריסה תלוי בזמן הכולל שלוקח להתקין את החבילות הנדרשות. אחרי הפריסה, remote_agent תואם למכונה של local_agent שפועלת ב-Agent Platform, ואפשר לשלוח אליה שאילתות או למחוק אותה.

האובייקט remote_agent תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

  • remote_agent.api_resource עם מידע על הסוכן שנפרס. אפשר גם להפעיל את remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות שנתמכות על ידי remote_agent. פרטים נוספים זמינים בקטע פעולות נתמכות.
  • remote_agent.api_client שמאפשר אינטראקציות סינכרוניות בין שירותים.
  • remote_agent.async_api_client שמאפשר אינטראקציות אסינכרוניות עם השירות.

אופציונלי: קבלת מזהה המשאב של הנציג

לכל סוכן שנפרס יש מזהה ייחודי. כדי לקבל את שם המשאב של הנציג שפרסתם, אתם יכולים להריץ את הפקודה הבאה:

remote_agent.api_resource.name

התגובה אמורה להיראות כמו המחרוזת הבאה:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

כאשר

אופציונלי: הצגת רשימה של הפעולות הנתמכות

לכל נציג פרוס יש רשימה של פעולות נתמכות. כדי לקבל את רשימת הפעולות שנתמכות על ידי הנציג שנפרס, אפשר להשתמש ב-AgentRuntime.operation_schemas:

remote_agent.operation_schemas()

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

אופציונלי: מתן הרשאות לסוכן שנפרס

אם צריך להעניק לסוכן שנפרס הרשאות נוספות, פועלים לפי ההוראות במאמר הגדרת הזהות וההרשאות של הסוכן.

אופציונלי: פריסת נציגים עם תשתית ארגונית

כדי לפרוס את הנציג בסביבה מלאה שכוללת שכבות אבטחה ופיקוח, מעתיקים ומתאימים אישית את התבניות הבאות של Application Design Center:

המאמרים הבאים

מדריך

איך מנהלים סוכנים שנפרסו בסביבת זמן הריצה המנוהלת של Agent Platform.

מדריך

שימוש בסוכן עם Agent Platform Runtime.