Computer Use 빠른 시작

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. 서비스별 약관 이 기능은 AI 에이전트를 위한 샌드박스 환경을 제공하므로 '에이전트 AI 서비스' 서비스별 약관이 적용됩니다. 이 기능을 활용하려면 AI 에이전트에 대한 전체 네트워크 액세스를 사용 설정해야 하므로, 사용 설정하기 전에 적용 가능한 보호 조치 (인간 감독 포함) 및 조직의 정책을 고려하세요. 기본 제공 컴퓨터 사용 보호 조치의 경우 Agent Platform Computer Use Tool을 고려하세요.

GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

이 페이지에서는 직접 API 호출을 통해 컴퓨터 사용 샌드박스 환경을 만들고 사용하는 방법을 보여줍니다. 이 빠른 시작에서는 다음 작업을 수행합니다.

• 샌드박스에 액세스할 수 있도록 Agent Platform 인스턴스를 만듭니다.
• 컴퓨터 사용 샌드박스를 만듭니다.
• 샌드박스의 액세스 토큰을 생성합니다.
• 상태를 확인하는 요청을 보냅니다.
• 리소스를 정리합니다.

시작하기 전에

프로젝트 및 환경 설정

프로젝트 설정

계정에 로그인합니다. Google Cloud 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가하세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

필요한 역할 가져오기

샌드박스를 사용하고 토큰을 생성하려면 다음 역할이 필요합니다.

• 프로젝트의 Agent Platform 사용자 (roles/aiplatform.user).
• 토큰 생성에 사용되는 서비스 계정의 서비스 계정 토큰 생성자 (roles/iam.serviceAccountTokenCreator).
• 토큰 생성에 사용되는 서비스 계정에는 프로젝트의 Agent Platform 사용자 (roles/aiplatform.user) 역할도 있어야 합니다.

라이브러리 설치

Agent Platform SDK를 설치합니다. posix-terminal pip install google-cloud-aiplatform>=1.112.0

Agent Platform 인스턴스 만들기

샌드박스를 사용하려면 먼저 Agent Platform 인스턴스를 만들어야 합니다.

import vertexai
client = vertexai.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
agent_instance = client.agent_engines.create()
agent_instance_name = agent_instance.api_resource.name

다음을 바꿉니다.

• 'PROJECT_ID': 프로젝트 ID입니다. Google Cloud
• 'LOCATION': 인스턴스의 리전 (예: us-central1).

컴퓨터 사용 템플릿 만들기

컴퓨터 사용 샌드박스를 만들 때 사용할 샌드박스 템플릿을 만듭니다.

# Create a default Computer Use sandbox template
templates_client = client.agent_engines.sandboxes.templates
tmplt_operation = templates_client.create(
    name=agent_instance_name,
    display_name='DISPLAY_NAME',
    config={
        "default_container_environment": {
            "default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
        },
        "egress_control_config": {
            "internet_access": True,
        },
    },
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")

컴퓨터 사용 샌드박스 만들기

템플릿에서 샌드박스 환경을 만듭니다.

# Create a sandbox environment referencing the template
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")

액세스 토큰 생성

샌드박스와 상호작용하려면 서비스 계정을 사용하여 JSON 웹 토큰 (JWT) 액세스 토큰을 생성합니다.

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.agent_engines.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

SERVICE_ACCOUNT_EMAIL을 서비스 계정 토큰 생성자 역할이 있는 서비스 계정의 이메일로 바꿉니다.

샌드박스로 요청 전송

샌드박스 API 서버에 HTTP GET 요청을 보내 상태를 확인합니다.

response = client.agent_engines.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

정리

요금이 발생하지 않도록 하려면 이 빠른 시작에서 만든 리소스를 삭제합니다.

client.agent_engines.sandboxes.delete(name=sandbox.name)
agent_instance.delete()

다음 단계

• 샌드박스 수명 주기 관리를 위한 스냅샷을 살펴봅니다.