יצירה וניהול של סוכנים

במדריך הזה מוסבר איך ליצור, לאחזר, להציג, לעדכן ולמחוק משאבים של סוכנים בהתאמה אישית שמשתמשים ב-Managed Agents API ב-Agent Platform, ואיך להגדיר את סביבת הסוכן, את הכלים של שרת Model Context Protocol‏ (MCP) ואת המיומנויות.

לפני שמתחילים

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

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: Agent Platform User (roles/aiplatform.user) or Agent Platform Administrator (roles/aiplatform.admin)

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.
  5. אם אתם מתכננים להשתמש ב Cloud de Confiance by S3NS כלים של Model Context Protocol‏ (MCP) עם הנציג, אתם צריכים לתת את התפקיד "משתמש בכלי MCP" (roles/mcp.toolUser) גם לחשבון המשתמש וגם לחשבון השירות המשויך.

יצירת סוכן

כדי ליצור סוכן חדש בהתאמה אישית, משתמשים ב-method‏ CreateAgent. זו פעולה ממושכת.

הנציג הבסיסי

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

כשיוצרים נציג, יש רק ערך אחד שנתמך בשביל base_agent: antigravity-preview-05-2026.

יצירת סוכן בסיסי

כדי ליצור סוכן בסיסי עם כלים שמוגדרים כברירת מחדל ויעד טעינה של Google Cloud Storage, שולחים בקשת POST:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.

  • ‫AGENT_ID: המזהה הייחודי בהתאמה אישית של הנציג החדש. מזהי נציגים בהתאמה אישית חייבים לעמוד במגבלות הבאות:

    • השם צריך להיות באורך של 1 עד 63 תווים.
    • השם יכול להכיל רק אותיות קטנות, מספרים ומקפים.
    • הוא צריך להתחיל באות ולהסתיים באות או במספר.

  • ‫BASE_AGENT: השם של הנציג הבסיסי שרוצים להרחיב. משתמשים ב-antigravity-preview-05-2026.

  • ‫AGENT_DESCRIPTION: סיכום קצר של היקף הסוכן.

  • ‫INSTRUCTIONS: הוראות מערכת או פרסונה שרוצים להגדיר לנציג.

  • ‫GCS_BUCKET: החלק של נתיב התיקייה בקטגוריה של Google Cloud Storage שנטענה (לדוגמה, gs://cymbal-bucket-name). הערה: כדי לטעון קטגוריה מפרויקט אחר, צריך לתת לחשבון השירות של הפרויקט גישה מסוג read ו-write לקטגוריה.

  • ‫network: מטעמי אבטחה, הגישה לרשת בסביבה מושבתת. צריך לציין allowlist כדי לאפשר גישה. שימוש ב-* כדומיין ב-allowlist מאפשר חיבורים לכל הדומיינים, ומספק גישה בלתי מוגבלת לרשת.

שיטת ה-HTTP וכתובת ה-URL

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents

גוף בקשת JSON

{
  "id": "AGENT_ID",
  "base_agent": "BASE_AGENT",
  "description": "AGENT_DESCRIPTION",
  "system_instruction": "INSTRUCTIONS",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_BUCKET",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

הפקודה curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "system_instruction": "INSTRUCTIONS",
      "tools": [
          {"type": "code_execution"},
          {"type": "filesystem"},
          {"type": "google_search"},
          {"type": "url_context"}
      ],
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_BUCKET",
                  "target": "/.agent"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

תשובה לדוגמה

{
  "name": "projects/1234567890/locations/global/agents/my-first-agent/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-12T23:50:16.933752Z",
      "updateTime": "2026-05-12T23:50:16.933752Z"
    }
  }
}

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    system_instruction="INSTRUCTIONS",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_BUCKET",
                "target": "/.agent",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    system_instruction: "INSTRUCTIONS",
    tools: [
        { type: "code_execution" },
        { type: "google_search" },
        { type: "url_context" },
    ],
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_BUCKET",
                target: "/.agent",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

יצירת סוכן באמצעות כלים מאינטראקציה ישירה של Google

כדי ליצור נציג עם כלים של Google (כמו Grounding with Google Search ו-URL context), מוסיפים את הכלים האלה לרשימה tools בהגדרות של הנציג:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.

  • ‫AGENT_ID: המזהה הייחודי בהתאמה אישית של הנציג החדש. מזהי נציגים בהתאמה אישית חייבים לעמוד במגבלות הבאות:

    • השם צריך להיות באורך של 1 עד 63 תווים.
    • השם יכול להכיל רק אותיות קטנות, מספרים ומקפים.
    • הוא צריך להתחיל באות ולהסתיים באות או במספר.

  • ‫AGENT_DESCRIPTION: סיכום קצר של היקף הסוכן.

גוף בקשת JSON

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ],
  "base_environment": {
    "type": "remote",
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}

הפקודה curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ],
      "base_environment": {
          "type": "remote",
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

יצירת נציג עם הגדרות MCP

אתם יכולים ליצור סוכן עם כלים מוגדרים מראש של שרת MCP באמצעות Managed Agents API ב-Agent Platform.

לפני שמתחילים

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

  • מקצים את התפקיד משתמש בכלי MCP (roles/mcp.toolUser) בניהול זהויות והרשאות גישה (IAM) גם לחשבון המשתמש וגם לחשבון השירות המשויך.

  • מוודאים ששרתי ה-MCP בהגדרות שלכם מתקשרים באמצעות HTTP POST רגיל כדי להציג כלים ולהפעיל אותם. כדי להשתמש ב-Managed Agents API ב-Agent Platform, שרתי ה-MCP המרוחקים צריכים להיות שרתי HTTP שניתן להעביר בסטרימינג. שרתי ה-MCP צריכים להטמיע את פרוטוקול התעבורה של MCP ב-HTTP עם סטרימינג, שבו tools/list ו-tools/call נשלחים כ-JSON-RPC דרך HTTP POST.

    אין תמיכה בהעברת HTTP+SSE עם שתי נקודות קצה (זרם GET /sse נפרד לטווח ארוך) שהוצאה משימוש.

אישור שרתי MCP שמתארחים ב-Google

אם אתם משתמשים בטוקן למוכ"ז כדי לאשר שרתי MCP שמתארחים ב-Google (כמו BigQuery), בצעו את השלבים הבאים:

  1. הוספת היקפי הרשאות של OAuth: מוסיפים את היקפי ההרשאות הנדרשים של OAuth 2.0 לאסימון האימות. לדוגמה, כדי להשתמש ב-MCP של BigQuery, צריך לכלול את ההיקפים הרלוונטיים של BigQuery בבקשה.
  2. אימות הגישה: בודקים אם אפשר לגשת לשרת ה-MCP עם ההיקפים החדשים שהגדרתם. כדי לעשות את זה, בודקים את תהליך ההרשאה ב-OAuth Playground.
  3. שימוש בכותרות: בפלטפורמות Google MCP כמו BigQuery, צריך לכלול את הכותרת X-Goog-User-Project שמוגדרת לשם הפרויקט במפה headers.

לדוגמה, גוף הבקשה בפורמט JSON שמשמש ליצירת נציג שמשתמש ב-MCP של BigQuery ייראה בערך כך:

{
  "name": "projects/<projectname>/locations/global/agents/data-analyst",
  "id": "data-analyst",
  "system_instruction": "You are a data analyst. Use the provided tools and data to perform analysis.",
  "tools": [
    { "type": "code_execution" },
    { "type": "filesystem" },
    { "type": "google_search" },
    { "type": "url_context" },
    {
      "type": "mcp_server",
      "name": "bigquery-mcp",
      "url": "https://bigquery.googleapis.com/mcp",
      "headers": {
        "Authorization": "Bearer ya29.a0AQyyyy",
        "X-Goog-User-Project": "project-nameyyyy"
      }
    }
  ],
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-1",
        "target": "/.agent/agents-1"
      }
    ],
    "network": {
      "allowlist": [ { "domain": "*" } ]
    }
  },
  "base_agent": "antigravity-preview-05-2026",
  "object": "agent"
}

יצירת הסוכן

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

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.

  • ‫AGENT_ID: המזהה הייחודי בהתאמה אישית של הנציג החדש. מזהי נציגים בהתאמה אישית חייבים לעמוד במגבלות הבאות:

    • השם צריך להיות באורך של 1 עד 63 תווים.
    • השם יכול להכיל רק אותיות קטנות, מספרים ומקפים.
    • הוא צריך להתחיל באות ולהסתיים באות או במספר.

  • ‫AGENT_DESCRIPTION: סיכום קצר של היקף הסוכן.

  • ‫MCP_SERVER_NAME: שם תיאורי לכלי ה-MCP.

  • ‫MCP_SERVER_URL: כתובת ה-URL של שער ה-HTTP המרוחק של שרת ה-MCP.

  • ‫MCP_HEADER_KEY: אופציונלי. שם הכותרת לאימות (לדוגמה, Authorization).

  • ‫MCP_HEADER_VALUE: אופציונלי. הטוקן למוכ"ז לאימות (לדוגמה, Bearer <token>).

גוף בקשת JSON

{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "description": "AGENT_DESCRIPTION",
  "tools": [
    {
      "type": "mcp_server",
      "name": "MCP_SERVER_NAME",
      "url": "MCP_SERVER_URL",
      "headers": {
        "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
      }
    }
  ]
}

הפקודה curl

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "description": "AGENT_DESCRIPTION",
      "tools": [
          {
              "type": "mcp_server",
              "name": "MCP_SERVER_NAME",
              "url": "MCP_SERVER_URL",
              "headers": {
                  "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    description="AGENT_DESCRIPTION",
    tools=[
        {
            "type": "mcp_server",
            "name": "MCP_SERVER_NAME",
            "url": "MCP_SERVER_URL",
            "headers": {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE"
            },
        }
    ],
)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    description: "AGENT_DESCRIPTION",
    tools: [
        {
            type: "mcp_server",
            name: "MCP_SERVER_NAME",
            url: "MCP_SERVER_URL",
            headers: {
                "MCP_HEADER_KEY": "MCP_HEADER_VALUE",
            },
        },
    ],
});

איך מצרפים מיומנויות לסוכן

כדי לטעון מיומנות לשימוש חוזר ישירות כשיוצרים את הסוכן, צריך להוסיף אותה בתוך base_environment.sources.

אפשר לצרף מיומנויות באחת מהשיטות הבאות:

  • מרשם המיומנויות: מצרפים מיומנות שרשומה בפרויקט במרשם המיומנויות.

  • ‫Google Cloud Storage: צירוף מיומנויות בהתאמה אישית ישירות מקטגוריה של Cloud Storage.

    כדי שהנציג יוכל למצוא את המיומנויות בקלות, מומלץ להעלות אותן לתיקייה /.agent/skills בסביבה.

מיומנויות CLI

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

צירוף מיומנות ממאגר המיומנויות

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

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: המזהה הייחודי בהתאמה אישית של הנציג החדש. מזהי סוכנים בהתאמה אישית חייבים לעמוד במגבלות הבאות:
    • השם צריך להיות באורך של 1 עד 63 תווים.
    • השם יכול להכיל רק אותיות קטנות, מספרים ומקפים.
    • הוא צריך להתחיל באות ולהסתיים באות או במספר.
  • ‫SKILL_RESOURCE_NAME: נתיב המשאב של המיומנות או רשימת המיומנויות שרוצים לטעון. אפשר לציין אחד מהפורמטים הבאים:
    • מיומנות (גרסת ברירת המחדל): projects/{projectID}/locations/{location}/skills/{skillName}
    • גרסה ספציפית: projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • רשימת המיומנויות: projects/{projectID}/locations/{location}/skills. הפעולה הזו טוענת עד 100 מיומנויות מה-project/location שצוין לסביבת ארגז החול.
    מידע נוסף זמין במאמר רשימת מיומנויות.
גוף בקשת JSON
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
הפקודה curl
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "skill_registry",
                "source": "SKILL_RESOURCE_NAME",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "skill_registry",
                source: "SKILL_RESOURCE_NAME",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

צירוף סקיל מ-Google Cloud Storage

אפשר גם לצרף מיומנויות בהתאמה אישית ישירות מקטגוריה של Cloud Storage כשיוצרים את הסוכן.

שימו לב לדרישות הבאות כשאתם טוענים מיומנויות מ-Cloud Storage:

  • דרישות העלאה: צריך להעלות את כל תיקיית הסקיל לקטגוריה.
  • אין אימות תוכן: הקצה העורפי לא מאמת את תוכן התיקייה לפני ההתקנה, אלא מתנהג כמו העלאת תיקייה רגילה.
  • מגבלות גודל: כל הקבצים המצורפים כפופים למגבלות הזיכרון של סביבת ארגז החול (עד 4GiB של זיכרון RAM בסך הכול).
  • שיטות מומלצות: כדי שהמיומנות תהיה איכותית, כדאי להכין את הקבצים בתיקיית המיומנות ולסדר אותם לפי המוסכמות שמתוארות בכתובת agentskills.io/home.

כדי לצרף מיומנות מ-Google Cloud Storage כשיוצרים את הנציג:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: המזהה הייחודי בהתאמה אישית של הנציג החדש. מזהי סוכנים בהתאמה אישית חייבים לעמוד במגבלות הבאות:
    • השם צריך להיות באורך של 1 עד 63 תווים.
    • השם יכול להכיל רק אותיות קטנות, מספרים ומקפים.
    • הוא צריך להתחיל באות ולהסתיים באות או במספר.
  • ‫GCS_SOURCE_PATH: הנתיב לקטגוריה של Google Cloud Storage שמכילה את תיקיית המיומנות (לדוגמה, gs://cymbal-bucket-name/my-skill-folder).
גוף בקשת JSON
{
  "id": "AGENT_ID",
  "base_agent": "antigravity-preview-05-2026",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
הפקודה curl
curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "id": "AGENT_ID",
      "base_agent": "antigravity-preview-05-2026",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "GCS_SOURCE_PATH",
                  "target": "./skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.create(
    id="AGENT_ID",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "GCS_SOURCE_PATH",
                "target": "./skills",
            }
        ],
        "network": {
            "allowlist": [{"domain": "*"}]
        },
    },
)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.create({
    id: "AGENT_ID",
    base_agent: "antigravity-preview-05-2026",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "GCS_SOURCE_PATH",
                target: "./skills",
            },
        ],
        network: {
            allowlist: [{ domain: "*" }],
        },
    },
});

הצגת רשימת הסוכנים

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

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של סוכני הרישום. יש תמיכה רק באזור global.
  • ‫PAGE_SIZE: אופציונלי. מספר הנציגים המקסימלי שיוחזר בכל דף. ערך ברירת המחדל הוא 10, והערך המקסימלי הוא 100.
  • ‫PAGE_TOKEN: אופציונלי. טוקן של דף שהתקבל מתשובה קודמת של ListAgents. צריך להזין את הטוקן כדי לאחזר את דף התוצאות הבא.

אם מספר הנציגים שצריך להחזיר גדול מהערך של PAGE_SIZE, התגובה של ListAgents כוללת את השדה nextPageToken. כדי לאחזר את הדף הבא של הנציגים, צריך להעביר את הערך של nextPageToken בתור הפרמטר PAGE_TOKEN בבקשת ה-ListAgents הבאה. חוזרים על התהליך הזה עד שהשדה nextPageToken לא מוחזר יותר בתגובה.

שיטת ה-HTTP וכתובת ה-URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

הפקודה curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

תשובה לדוגמה

{
  "agents": [
    {
      "name": "projects/1234567890/locations/global/agents/my-first-agent",
      "id": "my-first-agent",
      "created": "2026-05-12T23:50:16.933Z",
      "updated": "2026-05-12T23:50:21.159Z",
      "systemInstruction": "You are a helpful assistant to user."
    }
  ],
  "nextPageToken": "ABCDEFGHIJKLMNOPQRSTUVWXYZ=="
}

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.list()

for agent in response.agents:
    print(agent)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.list();

if (response.agents) {
    for (const agent of response.agents) {
        console.log(agent);
    }
}

הצגת סוכן

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

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .

  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.

  • ‫AGENT_ID: המזהה הייחודי של הגדרת הסוכן בהתאמה אישית שאתם מבקשים.

שיטת ה-HTTP וכתובת ה-URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

הפקודה curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

תשובה לדוגמה

{
  "name": "projects/vertex-agent-fishfood/locations/global/agents/my-first-agent",
  "id": "my-first-agent",
  "created": "2026-05-12T23:50:16.933Z",
  "updated": "2026-05-12T23:50:21.159Z",
  "systemInstruction": "You are a helpful assistant to user.",
  "tools": [
    {"type": "code_execution"},
    {"type": "filesystem"},
    {"type": "google_search"},
    {"type": "url_context"}
  ],
  "description": "A demo agent showcasing Environment and Skills use case.",
  "baseEnvironment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "gs://agents-api-sample-skills",
        "target": "/.agent"
      }
    ],
    "network": {
      "allowlist": [
        {"domain": "*"}
      ]
    }
  },
  "baseAgent": "antigravity-preview-05-2026",
  "object": "agent"
}

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

agent = client.agents.get(id="AGENT_ID")
print(agent)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const agent = await client.agents.get("AGENT_ID");
console.log(agent);

עדכון סוכן

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

עדכון של סוכן בסיסי

כדי לעדכן את הוראות המערכת של הנציג, שולחים בקשת PATCH עם update_mask=system_instruction:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: הגדרת סוכן היעד לעדכון התיקון.
  • ‫NEW_INSTRUCTIONS: המבנה או התיאור המעודכנים של ההוראות שרוצים להחליף.

שיטת ה-HTTP וכתובת ה-URL

PATCH https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction

גוף בקשת JSON

{
  "name": "AGENT_ID",
  "system_instruction": "NEW_INSTRUCTIONS"
}

הפקודה curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=system_instruction" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "system_instruction": "NEW_INSTRUCTIONS"
  }'

Python

JavaScript

עדכון סוכן באמצעות כלים מאינטראקציה ישירה של Google

כדי לעדכן סוכן ולאפשר כלים של Google (כמו עיגון באמצעות חיפוש Google ו-URL Context), שולחים בקשת PATCH עם update_mask=tools:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: מזהה הסוכן המטורגט.

גוף בקשת JSON

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "google_search"
    },
    {
      "type": "url_context"
    }
  ]
}

הפקודה curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "google_search"
          },
          {
              "type": "url_context"
          }
      ]
  }'

עדכון סוכן עם הגדרות MCP

כדי לשנות את כלי ה-MCP שמצורפים לנציג, שולחים בקשת PATCH עם update_mask=tools:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: מזהה הנציג המטורגט.
  • ‫NEW_MCP_SERVER_NAME: התווית המעודכנת של כלי ה-MCP.
  • ‫NEW_MCP_SERVER_URL: הפרמטר החדש של נקודת הקצה של כתובת ה-URL של השרת.
  • ‫NEW_MCP_HEADER_KEY: אופציונלי. שם הכותרת לאימות (לדוגמה, Authorization).
  • ‫NEW_MCP_HEADER_VALUE: אופציונלי. טוקן האימות למוכ"ז (לדוגמה, Bearer <token>).

גוף בקשת JSON

{
  "name": "AGENT_ID",
  "tools": [
    {
      "type": "mcp_server",
      "name": "NEW_MCP_SERVER_NAME",
      "url": "NEW_MCP_SERVER_URL",
      "headers": {
        "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
      }
    }
  ]
}

הפקודה curl

curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=tools" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "tools": [
          {
              "type": "mcp_server",
              "name": "NEW_MCP_SERVER_NAME",
              "url": "NEW_MCP_SERVER_URL",
              "headers": {
                  "NEW_MCP_HEADER_KEY": "NEW_MCP_HEADER_VALUE"
              }
          }
      ]
  }'

Python

JavaScript

איך מצרפים מיומנויות לסוכן

כדי לצרף או לשנות סקילים ב-base_environment.sources במהלך עדכון של הסוכן, שולחים בקשת PATCH באמצעות update_mask=base_environment.

אפשר לצרף מיומנויות באחת מהשיטות הבאות:

  • מרשם המיומנויות: מצרפים מיומנות שרשומה בפרויקט במרשם המיומנויות.

  • ‫Google Cloud Storage: צירוף מיומנויות בהתאמה אישית ישירות מקטגוריה של Cloud Storage.

צירוף מיומנות ממאגר המיומנויות

כדי לצרף מיומנות שרשומה במאגר המיומנויות:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: מזהה הנציג המטורגט.
  • ‫NEW_SKILL_RESOURCE_NAME: נתיב המשאב של המיומנות או רשימת המיומנויות שרוצים לטעון. אפשר לציין אחד מהפורמטים הבאים:
    • מיומנות (גרסת ברירת המחדל): projects/{projectID}/locations/{location}/skills/{skillName}
    • גרסת המיומנות (הצמדה לגרסה ספציפית): projects/{projectID}/locations/{location}/skills/{skillName}/skill_versions/{skill_version}
    • ‫ListSkills (הצגת כל המיומנויות): projects/{projectID}/locations/{location}/skills. הפעולה הזו טוענת עד 100 מיומנויות בפרויקט או במיקום לסביבת ארגז החול.
    מידע נוסף על איתור הערך של name עבור NEW_SKILL_RESOURCE_NAME זמין במאמר רשימת מיומנויות.
גוף בקשת JSON
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "skill_registry",
        "source": "NEW_SKILL_RESOURCE_NAME",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
הפקודה curl
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "skill_registry",
                  "source": "NEW_SKILL_RESOURCE_NAME",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

צירוף סקיל מ-Google Cloud Storage

אפשר גם לצרף מיומנויות בהתאמה אישית ישירות מקטגוריה של Cloud Storage כשיוצרים את הסוכן.

שימו לב לדרישות הבאות כשאתם טוענים מיומנויות מ-Cloud Storage:

  • דרישות העלאה: צריך להעלות את כל תיקיית הסקיל לקטגוריה.
  • אין אימות תוכן: הקצה העורפי לא מאמת את תוכן התיקייה לפני ההתקנה, אלא מתנהג כמו העלאת תיקייה רגילה.
  • מגבלות גודל: כל הקבצים המצורפים כפופים למגבלות הזיכרון של סביבת ארגז החול (עד 4GiB של זיכרון RAM בסך הכול).
  • שיטות מומלצות: כדי שהמיומנות תהיה איכותית, כדאי להכין את הקבצים בתיקיית המיומנות ולסדר אותם לפי המוסכמות שמתוארות בכתובת agentskills.io/home.

כדי לצרף מיומנות מ-Google Cloud Storage:

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: מזהה הנציג המטורגט.
  • ‫NEW_GCS_SOURCE_PATH: הנתיב לקטגוריה של Google Cloud Storage שמכילה את תיקיית המיומנות (לדוגמה, gs://cymbal-bucket-name/my-skill-folder).
גוף בקשת JSON
{
  "name": "AGENT_ID",
  "base_environment": {
    "type": "remote",
    "sources": [
      {
        "type": "gcs",
        "source": "NEW_GCS_SOURCE_PATH",
        "target": "/.agent/skills"
      }
    ],
    "network": {
      "allowlist": [
        { "domain": "*" }
      ]
    }
  }
}
הפקודה curl
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID?update_mask=base_environment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -d '{
      "name": "AGENT_ID",
      "base_environment": {
          "type": "remote",
          "sources": [
              {
                  "type": "gcs",
                  "source": "NEW_GCS_SOURCE_PATH",
                  "target": "/.agent/skills"
              }
          ],
          "network": {
              "allowlist": [
                  { "domain": "*" }
              ]
          }
      }
  }'

Python

JavaScript

מחיקת סוכן

כדי למחוק הגדרה ספציפית של סוכן בהתאמה אישית, שולחים בקשת DELETE. זוהי פעולה ממושכת שמוחקת את ההגדרה באופן סופי. אם מוחקים את Agent Runtime, זהות הסוכן שלו מבוטלת. בכל מדיניות גישה מאוחדת (UAP) ב-IAM שמעניקה הרשאות לחשבון המשתמש הזה, החשבון שבוטל נשאר בכללים שלה. בנוסף, הקישור למדיניות נשאר פעיל. כדי להסיר חשבון משתמש לא פעיל, מעדכנים את ה-UAP ומסירים את החשבון מהכללים שלו. אם במדיניות אין יותר חשבונות משתמשים פעילים, מוחקים את קישור המדיניות.

כשמוחקים נציג, צריך לספק את כל המידע הנדרש בכתובת ה-URL ולא לכלול גוף בקשה בפורמט JSON.

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: האזור של הנציג. יש תמיכה רק באזור global.
  • ‫AGENT_ID: המזהה של הנציג שמוחקים.

שיטת ה-HTTP וכתובת ה-URL

DELETE https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID

הפקודה curl

curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

תשובה לדוגמה

{
  "name": "projects/1234567890/locations/global/operations/234567890123",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.DeleteOperationMetadata",
    "genericMetadata": {
      "createTime": "2026-05-13T02:15:45.936287Z",
      "updateTime": "2026-05-13T02:15:45.936287Z"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

Python

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

from google import genai

client = genai.Client(
    vertexai=True,
    project="PROJECT_ID",
    location="global",
)

response = client.agents.delete(id="AGENT_ID")
print(response)

JavaScript

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

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
    vertexai: true,
    project: "PROJECT_ID",
    location: "global",
});

const response = await client.agents.delete("AGENT_ID");
console.log(response);

קבלת פרטים על פעולה ממושכת

פעולות כמו CreateAgent,‏ UpdateAgent ו-DeleteAgent הן אסינכרוניות. התגובה הראשונית מה-API מחזירה את השדה name שמכיל את מזהה הפעולה. כדי לבדוק את ההתקדמות, משתמשים ב-GetOperation במזהה הזה.

REST

משתני בקשה

לפני ששולחים קריאה ל-API, צריך להחליף את הערכים הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
  • ‫LOCATION: המיקום האזורי של הפעולה. יש תמיכה רק באזור global.
  • ‫OPERATION_ID: מזהה הפעולה שחולץ מהשדה name בתגובה הראשונית של ה-LRO.

שיטת ה-HTTP וכתובת ה-URL

GET https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

הפקודה curl

curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)"

Python

JavaScript

הגדרת הגישה לרשת

כברירת מחדל, כשיוצרים נציגים באמצעות Agents API, ארגז החול משבית את הגישה לרשת. כדי לאפשר גישה בלתי מוגבלת, משתמשים ב-*.

לדוגמה, שימוש ב-* ב-allowlist, כמו שמוצג בקוד הבא, נותן גישה לכל הדומיינים:

"base_environment": {
    "type": "remote",
    "sources": [
        {
            "type": "skill_registry",
            "source": "SKILL_RESOURCE_NAME",
            "target": "./skills"
        }
    ],
    "network": {
        "allowlist": [{"domain": "*"}]
    }
}

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

מדריך

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