에이전트 만들기 및 관리

이 가이드에서는 에이전트 플랫폼에서 Managed Agents API를 사용하는 커스텀 에이전트 리소스를 만들고, 검색하고, 나열하고, 업데이트하고, 삭제하는 방법과 에이전트 환경, 모델 컨텍스트 프로토콜 (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 모델 컨텍스트 프로토콜 (MCP) 도구를 사용하려면 사용자 계정과 연결된 서비스 계정 모두에 MCP 도구 사용자 (roles/mcp.toolUser) 역할을 부여합니다.

에이전트 만들기

새 커스텀 에이전트를 만들려면 CreateAgent 메서드를 사용합니다. 이는 장기 실행 작업입니다.

기본 에이전트

base_agent는 에이전트에 추론 기능과 실행 환경에 대한 액세스 권한을 제공하는 핵심 조정 하네스입니다. 환경에 기술과 라이브러리를 삽입할 수 있으며 코드 실행, 파일 시스템 작업, 그라운딩을 통한 검색을 위한 서비스 측 도구에 액세스할 수 있습니다.

에이전트를 만들 때 base_agent에 지원되는 값은 antigravity-preview-05-2026 하나뿐입니다.

기본 에이전트 만들기

기본 도구와 Google Cloud Storage 마운트 타겟이 있는 기본 에이전트를 만들려면 POST 요청을 보냅니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.

  • AGENT_ID: 새 에이전트의 고유한 커스텀 식별자입니다. 커스텀 에이전트 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 검색으로 그라운딩 및 URL 컨텍스트와 같은 Google 퍼스트 파티 도구를 사용하여 에이전트를 만들려면 에이전트 구성의 tools 목록에 이러한 도구를 추가합니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.

  • AGENT_ID: 새 에이전트의 고유한 커스텀 식별자입니다. 커스텀 에이전트 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 구성으로 에이전트 만들기

Agent Platform에서 Managed Agents API를 사용하여 사전 구성된 MCP 서버 도구로 에이전트를 만들 수 있습니다.

시작하기 전에

사전 구성된 MCP 서버 도구를 사용하여 에이전트를 만들기 전에 다음을 수행합니다.

  • 사용자 계정과 연결된 서비스 계정 모두에 MCP 도구 사용자 (roles/mcp.toolUser) Identity and Access Management (IAM) 역할을 부여합니다.

  • 구성의 MCP 서버가 도구 목록 및 실행을 위해 표준 HTTP POST를 통해 통신하는지 확인합니다. Agent Platform의 Managed Agents API를 사용하려면 원격 MCP 서버가 스트리밍 가능한 HTTP 서버여야 합니다. MCP 서버는 MCP 스트리밍 가능 HTTP 전송을 구현해야 합니다. 여기서 tools/list 및 tools/call는 HTTP POST를 통해 JSON-RPC로 전송됩니다.

    지원 중단된 2개 엔드포인트 HTTP+SSE 전송 (별도의 장기 실행 GET /sse 스트림)은 지원되지 않습니다.

Google 호스팅 MCP 승인

Google 호스팅 MCP 서버(예: BigQuery)의 승인에 Bearer 토큰을 사용하는 경우 다음 단계를 완료합니다.

  1. OAuth 범위 추가: 필요한 OAuth 2.0 범위를 인증 토큰에 추가합니다. 예를 들어 BigQuery MCP를 사용하려면 요청에 관련 BigQuery 범위를 포함합니다.
  2. 액세스 검증: OAuth Playground에서 승인 흐름을 테스트하여 새로 구성된 범위로 MCP 서버에 액세스할 수 있는지 확인합니다.
  3. 헤더 사용: BigQuery와 같은 Google MCP의 경우 headers 맵에 프로젝트 이름으로 설정된 X-Goog-User-Project 헤더를 포함해야 합니다.

예를 들어 BigQuery MCP를 사용하는 에이전트를 만드는 데 사용되는 요청 JSON 본문은 다음과 유사합니다.

{
  "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 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.

  • AGENT_ID: 새 에이전트의 고유한 커스텀 식별자입니다. 커스텀 에이전트 ID는 다음 제약조건을 준수해야 합니다.

    • 1~63자(영문 기준)여야 합니다.
    • 소문자, 숫자, 하이픈만 포함해야 합니다.
    • 영문자로 시작하고 영문자나 숫자로 끝나야 합니다.

  • AGENT_DESCRIPTION: 에이전트 범위에 대한 간단한 요약입니다.

  • MCP_SERVER_NAME: MCP 도구를 설명하는 이름입니다.

  • MCP_SERVER_URL: MCP 서버의 원격 HTTP 게이트웨이 URL입니다.

  • MCP_HEADER_KEY: 선택사항. 인증 헤더의 이름입니다 (예: Authorization).

  • MCP_HEADER_VALUE: 선택사항. 인증 Bearer 토큰(예: 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 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 새 에이전트의 고유한 커스텀 식별자입니다. 커스텀 에이전트 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. 이렇게 하면 지정된 project/location에서 최대 100개의 기술이 샌드박스 환경에 마운트됩니다.
    자세한 내용은 기술 나열을 참조하세요.
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에서 기술 연결

또는 에이전트를 만들 때 Google Cloud Storage 버킷에서 직접 커스텀 기술을 연결할 수 있습니다.

Cloud Storage에서 기술을 마운트할 때는 다음 요구사항에 유의하세요.

  • 업로드 요구사항: 전체 기술 폴더를 버킷에 업로드해야 합니다.
  • 콘텐츠 검증 없음: 백엔드는 마운트하기 전에 폴더 콘텐츠를 검증하지 않습니다. 표준 폴더 업로드처럼 작동합니다.
  • 크기 제한: 모든 첨부파일은 샌드박스 환경 메모리 제한 (총 최대 4GiB RAM)을 따릅니다.
  • 권장사항: 최적의 기술 품질을 위해 agentskills.io/home에 설명된 규칙에 따라 기술 폴더의 파일을 구조화하고 준비합니다.

에이전트를 만들 때 Google Cloud Storage에서 기술을 연결하려면 다음 안내를 따르세요.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 새 에이전트의 고유한 커스텀 식별자입니다. 커스텀 에이전트 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 프로젝트 ID입니다.
  • LOCATION: 에이전트 목록의 리전 위치입니다. global 리전만 지원됩니다.
  • PAGE_SIZE: 선택사항. 페이지당 반환할 최대 에이전트 수입니다. 기본값은 10이고 최댓값은 100입니다.
  • PAGE_TOKEN: 선택사항. 이전 ListAgents 응답에서 수신한 페이지 토큰입니다. 후속 결과 페이지를 가져오려면 이 토큰을 제공하세요.

반환할 에이전트 수가 PAGE_SIZE보다 크면 ListAgents 응답에 nextPageToken 필드가 포함됩니다. 에이전트의 다음 페이지를 검색하려면 이 nextPageToken 값을 다음 ListAgents 요청에서 PAGE_TOKEN 매개변수로 전달합니다. 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 프로젝트 ID입니다.

  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.

  • AGENT_ID: 요청하는 커스텀 에이전트 구성의 고유 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 요청을 전송합니다. 에이전트 ID는 변경할 수 없지만 안내, 도구, 환경 변수와 같은 파라미터를 수정할 수 있습니다. update_mask 쿼리 매개변수를 사용하여 업데이트할 필드를 정확하게 지정합니다. 이렇게 하면 변경하려는 필드만 영향을 받고 다른 구성은 보존됩니다.

기본 에이전트 업데이트

에이전트의 시스템 안내를 업데이트하려면 update_mask=system_instruction를 사용하여 PATCH 요청을 전송합니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • 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 퍼스트 파티 (1P) 도구 (예: Google 검색을 사용한 그라운딩 및 URL 컨텍스트)를 사용 설정하도록 에이전트를 업데이트하려면 update_mask=tools를 사용하여 PATCH 요청을 전송합니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 대상 에이전트 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 도구를 수정하려면 update_mask=tools를 사용하여 PATCH 요청을 전송합니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 대상 에이전트 ID입니다.
  • NEW_MCP_SERVER_NAME: MCP 도구의 업데이트된 라벨입니다.
  • NEW_MCP_SERVER_URL: 서버의 새 URL 엔드포인트 매개변수입니다.
  • NEW_MCP_HEADER_KEY: 선택사항. 인증 헤더의 이름입니다 (예: Authorization).
  • NEW_MCP_HEADER_VALUE: 선택사항. 인증 Bearer 토큰입니다 (예: 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 내에서 기술을 연결하거나 수정하려면 update_mask=base_environment를 사용하여 PATCH 요청을 전송합니다.

다음 방법 중 하나를 사용하여 기술을 연결할 수 있습니다.

  • 스킬 레지스트리: 스킬 레지스트리에서 프로젝트 내에 등록된 스킬을 연결합니다.

  • Google Cloud Storage: Cloud Storage 버킷에서 직접 커스텀 기술을 연결합니다.

스킬 레지스트리에서 스킬 연결

스킬 레지스트리에 등록된 스킬을 연결하려면 다음 안내를 따르세요.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 대상 에이전트 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개의 기술이 샌드박스 환경에 마운트됩니다.
    NEW_SKILL_RESOURCE_NAME의 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에서 기술 연결

또는 에이전트를 만들 때 Google Cloud Storage 버킷에서 직접 커스텀 기술을 연결할 수 있습니다.

Cloud Storage에서 기술을 마운트할 때는 다음 요구사항에 유의하세요.

  • 업로드 요구사항: 전체 기술 폴더를 버킷에 업로드해야 합니다.
  • 콘텐츠 검증 없음: 백엔드는 마운트하기 전에 폴더 콘텐츠를 검증하지 않습니다. 표준 폴더 업로드처럼 작동합니다.
  • 크기 제한: 모든 첨부파일은 샌드박스 환경 메모리 제한 (총 최대 4GiB RAM)을 따릅니다.
  • 권장사항: 최적의 기술 품질을 위해 agentskills.io/home에 설명된 규칙에 따라 기술 폴더의 파일을 구조화하고 준비합니다.

Google Cloud Storage에서 기술을 연결하려면 다음 안내를 따르세요.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전 위치입니다. global 리전만 지원됩니다.
  • AGENT_ID: 대상 에이전트 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 요청을 보냅니다. 이는 장기 실행 작업이며 구성을 영구적으로 삭제합니다. 에이전트 런타임을 삭제하면 에이전트 ID가 무효화됩니다. 해당 주 구성원에게 권한을 부여하는 모든 IAM 통합 액세스 정책 (UAP)은 규칙에 사용 중지된 주 구성원을 유지합니다. 또한 정책 바인딩은 활성 상태로 유지됩니다. 사용 중지된 주 구성원을 삭제하려면 UAP를 업데이트하여 규칙에서 주 구성원을 삭제합니다. 정책에 더 이상 활성 주 구성원이 포함되지 않으면 정책 바인딩을 삭제합니다.

에이전트를 삭제할 때는 URL에 필요한 모든 정보를 제공하고 JSON 요청 본문을 포함하지 마세요.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 에이전트의 리전입니다. global 리전만 지원됩니다.
  • AGENT_ID: 삭제하려는 에이전트의 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 응답은 작업 ID가 포함된 name 필드를 반환합니다. 이 ID에서 GetOperation를 사용하여 진행 상황을 폴링합니다.

REST

요청 변수

API를 호출하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Cloud de Confiance by S3NS 프로젝트 ID입니다.
  • LOCATION: 작업의 리전 위치입니다. global 리전만 지원됩니다.
  • OPERATION_ID: 초기 LRO 응답의 name 필드에서 추출된 작업 ID입니다.

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": "*"}]
    }
}

다음 단계

가이드

런타임에 에이전트와 상호작용하고, 세션 상태를 관리하고, 구성을 동적으로 재정의하는 방법을 알아봅니다.