Computer Use 빠른 시작

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. 이 기능은 AI 에이전트를 위한 샌드박스 환경을 제공하므로 '에이전트 AI 서비스' 서비스별 약관이 적용됩니다. 이 기능을 사용하려면 AI 에이전트의 전체 네트워크 액세스를 사용 설정해야 하므로, 사용 설정하기 전에 관련 보호 수단 (인적 감독 포함)과 조직의 정책을 고려하세요. 내장 컴퓨터 사용 보호 수단의 경우 Agent Platform 컴퓨터 사용 도구를 고려하세요.

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

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

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

시작하기 전에

프로젝트 및 환경 설정

프로젝트 설정

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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 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

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 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

필요한 역할 가져오기

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

• 프로젝트의 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: Google Cloud 프로젝트 ID입니다.
• 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}")

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

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

참고: 기본적으로 샌드박스는 2시간 후에 만료됩니다. 샌드박스를 만들 때 ttl 필드를 설정하여 샌드박스 수명을 맞춤설정할 수 있습니다.

# Create a sandbox environment referencing the template.
# To customize the lifetime, set `ttl` to a duration string in seconds (for example, "3600s" for 1 hour).
create_operation = client.agent_engines.sandboxes.create(
    name=agent_instance_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
        "ttl": "3600s",  # Optional. Overrides the default 2-hour sandbox lifetime.
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")
print(f"Sandbox will expire at: {sandbox.expire_time}")

액세스 토큰 생성

샌드박스와 상호작용하려면 서비스 계정을 사용하여 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}")

특정 페이지로 이동하려면 HTTP POST 요청을 보냅니다.

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.agent_engines.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

다음 표에는 샌드박스로 전송할 수 있는 추가 메서드와 경로가 나와 있습니다.

메서드	경로	설명
GET	/	샌드박스 상태 점검 가져오기
POST	/tabs	새 탭을 만들고 세부정보를 반환합니다.
GET	/tabs	열려 있는 모든 탭의 세부정보를 나열합니다.
POST	/tabs/{tab_id}/activate	탭을 활성으로 설정하고 포그라운드로 가져옵니다.
삭제	/tabs/{tab_id}	특정 탭을 닫습니다.
GET	/cdp_ws_endpoint	CDP WebSocket 엔드포인트 경로를 반환합니다.
POST	/cdp	활성 탭에서 CDP 명령어를 실행합니다.
POST	/cdps	활성 탭에서 여러 CDP 명령어를 실행합니다.

지원되는 CDP 명령어 및 형식에 관한 자세한 내용은 CDP 사이트를 참고하세요.

삭제

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

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

다음 단계

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