כשפורסים סוכן ב-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 בזיכרון. השיטה הזו מתאימה במיוחד לנציגים עם מבנים שלא מכילים רכיבים מורכבים שלא ניתנים לסריאליזציה.
כדי להתחיל, מבצעים את השלבים הבאים:
- השלמת הדרישות המוקדמות
- אופציונלי: הגדרת הנציג לפריסה
- יצירת מכונה של Gemini Enterprise Agent Platform
- אופציונלי: קבלת מזהה המשאב של הנציג
- אופציונלי: רשימת הפעולות הנתמכות
- אופציונלי: מתן הרשאות לסוכן שנפרס
דרישות מוקדמות
לפני שפורסים נציג, צריך לבצע את המשימות הבאות:
אופציונלי: הגדרת הסוכן לפריסה
אתם יכולים להגדיר הגדרות אופציונליות לנציג. הדוגמאות בקטע הזה הן ב-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.
הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:
- שירות Agent Runtime מאחזר את קוד המקור מהגרסה שצוינה במאגר Git.
- השירות מתקין יחסי תלות מ-
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שמאפשר אינטראקציות אסינכרוניות עם השירות.
מאגר 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.
הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:
- שירות Agent Runtime משכפל את המאגר בגרסה שצוינה.
- השירות מתקין יחסי תלות מ-
requirements_file(אם הקובץ קיים). - השירות מפעיל את אפליקציית הנציג באמצעות
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בתיקיית השורש של המקור הארוז.
הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:
- ה-SDK של Agent Platform יוצר ארכיון
tar.gzשל הנתיבים שצוינו ב-source_packages. - הארכיון הזה מקודד ונשלח ישירות ל-Agent Platform API.
- שירות 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. }, )
הפריסה נמשכת כמה דקות, ובמהלכה מתבצעים השלבים הבאים ברקע:
- חבילה של פריטי המידע שנוצרו באופן מקומי:
-
*.pklקובץ pickle שתואם ל-local_agent. -
requirements.txtקובץ טקסט שמכיל את הדרישות של החבילה. -
dependencies.tar.gzקובץ tar שמכיל חבילות נוספות.
-
- החבילה מועלית ל-Cloud Storage (בתיקייה המתאימה) כדי להכין את פריטי המידע שנוצרו.
- מזהי ה-URI של Cloud Storage לפריטי המידע הרלוונטיים שנוצרו בתהליך הפיתוח (Artifacts) מצוינים ב-PackageSpec.
- שירות 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"
כאשר
PROJECT_IDהוא Google Cloud מזהה הפרויקט שבו הנציג שנפרס פועל.
LOCATIONהוא האזור שבו הנציג שנפרס פועל.
RESOURCE_IDהוא המזהה של הנציג שנפרס כמשאבreasoningEngine.
אופציונלי: הצגת רשימה של הפעולות הנתמכות
לכל נציג פרוס יש רשימה של פעולות נתמכות. כדי לקבל את רשימת הפעולות שנתמכות על ידי הנציג שנפרס, אפשר להשתמש ב-AgentRuntime.operation_schemas:
remote_agent.operation_schemas()
הסכימה של כל פעולה היא מילון שמתעד את המידע של שיטה לסוכן שאפשר לקרוא לה. קבוצת הפעולות הנתמכות תלויה במסגרת שבה השתמשתם כדי לפתח את הנציג:
אופציונלי: מתן הרשאות לסוכן שנפרס
אם צריך להעניק לסוכן שנפרס הרשאות נוספות, פועלים לפי ההוראות במאמר הגדרת הזהות וההרשאות של הסוכן.
אופציונלי: פריסת נציגים עם תשתית ארגונית
כדי לפרוס את הנציג בסביבה מלאה שכוללת שכבות אבטחה ופיקוח, מעתיקים ומתאימים אישית את התבניות הבאות של Application Design Center: