สภาพแวดล้อมใน Agent ที่มีการจัดการ

สภาพแวดล้อมคือแซนด์บ็อกซ์ Linux ที่มีการจัดการ ซึ่งช่วยให้ตัวแทนมีพื้นที่ที่แยกต่างหากเพื่อรันโค้ดและเก็บไฟล์ไว้ โดยสภาพแวดล้อมจะแยกออกจากบริบทการโต้ตอบ คุณจึงใช้สภาพแวดล้อมเดียวกันซ้ำในการโต้ตอบหลายครั้งหรือเริ่มต้นใหม่ได้ทุกเมื่อ

ตัวอย่างต่อไปนี้แสดงวิธีสร้างการโต้ตอบกับสภาพแวดล้อมระยะไกลใหม่และดึงข้อมูลรหัสของการโต้ตอบ

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib, verify the imports, and print the versions.",
    environment="remote",
)

print(f"Environment ID: {interaction.environment_id}")

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Install pandas and matplotlib, verify the imports, and print the versions.",
    environment: "remote",
});

console.log(`Environment ID: ${interaction.environment_id}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Install pandas and matplotlib, verify the imports, and print the versions.",
    "environment": "remote"
}'

พารามิเตอร์ environment

พารามิเตอร์ environment ยอมรับ 3 รูปแบบ ดังนี้

ฟอร์ม ตัวอย่าง กรณีที่ควรใช้
"remote" environment="remote" จัดเตรียมแซนด์บ็อกซ์ใหม่
รหัสสภาพแวดล้อม environment="env_abc123" ใช้แซนด์บ็อกซ์ที่มีอยู่ซ้ำพร้อมไฟล์และแพ็กเกจทั้งหมด
ออบเจ็กต์การกำหนดค่า environment={...} จัดเตรียมแซนด์บ็อกซ์ใหม่ที่มีแหล่งที่มา กฎเครือข่าย หรือทั้ง 2 อย่าง

ตัวอย่างต่อไปนี้แสดงวิธีใช้พารามิเตอร์ environment 3 วิธี

Python

from google import genai

client = genai.Client()

# Fresh sandbox
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a hello world script.",
    environment="remote",
)

# Reuse an existing sandbox
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Modify the script to accept a name argument.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
)

# New sandbox with sources
interaction_3 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="List all files and summarize the project.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife",
            }
        ],
    },
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

// Fresh sandbox
const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Write a hello world script.",
    environment: "remote",
});

// Reuse an existing sandbox
const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Modify the script to accept a name argument.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction.id,
});

// New sandbox with sources
const interaction3 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "List all files and summarize the project.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/octocat/Spoon-Knife",
                target: "/workspace/spoon-knife",
            },
        ],
    },
});

console.log(interaction.output_text);

REST

# Fresh sandbox
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "Write a hello world script."}],
    "environment": "remote"
}'

# Reuse an existing sandbox (replace $ENV_ID and $INTERACTION_ID with values from the previous response)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d "{
    \"agent\": \"antigravity-preview-05-2026\",
    \"input\": [{\"type\": \"text\", \"text\": \"Modify the script to accept a name argument.\"}],
    \"environment\": \"$ENV_ID\",
    \"previous_interaction_id\": \"$INTERACTION_ID\"
}"

# New sandbox with sources
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "List all files and summarize the project."}],
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife"
            }
        ]
    }
}'

กำหนดค่าสภาพแวดล้อม

วิธีหนึ่งในการตั้งค่าสภาพแวดล้อมคือการบอกตัวแทนว่าคุณต้องการติดตั้งอะไร ตัวแทนจะจัดการการแก้ปัญหาการพึ่งพาอาศัยกันและการแก้ปัญหา เมื่อสภาพแวดล้อมพร้อมแล้ว ให้บันทึก environment_id แล้วนำไปใช้ซ้ำ

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    environment="remote",
)

# Reuse the configured environment
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
)

# Reuse the configured environment
interaction_3 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Using the tools in /workspace/tools, list the files.",
    environment=interaction.environment_id,
    previous_interaction_id=interaction_2.id,
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    environment: "remote",
});

const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction.id,
});

const interaction3 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Using the tools in /workspace/tools, list the files.",
    environment: interaction.environment_id,
    previous_interaction_id: interaction2.id,
});
console.log(interaction.output_text);

REST

# Create interaction
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    "environment": "remote"
}'

ติดตั้งจากแหล่งที่มา

หากทราบแน่ชัดว่าตัวแทนต้องการไฟล์ใด ให้ติดตั้งไฟล์เหล่านั้นในการเรียกใช้ครั้งเดียวแทนการวนซ้ำ ออบเจ็กต์การกำหนดค่า environment ยอมรับอาร์เรย์ sources 3 ประเภท ดังนี้

ประเภทแหล่งที่มา ค่า type คำอธิบาย ขีดจำกัด
ที่เก็บ Git repository โคลนที่เก็บจาก URL ลงในแซนด์บ็อกซ์ที่ target 500 MB
Cloud Storage gcs คัดลอกไฟล์หรือไดเรกทอรีจาก Cloud Storage ลงในแซนด์บ็อกซ์ที่ target 2 GB
เนื้อหาแบบอินไลน์ inline เขียนเนื้อหาข้อความดิบลงในไฟล์ในแซนด์บ็อกซ์ที่ target 1 MB ต่อไฟล์, รวม 2 MB

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="List all files under /workspace and describe what you find.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife",
            },
            {
                "type": "gcs",
                "source": "gs://cloud-samples-data/bigquery/us-states/",
                "target": "/workspace/gcs-data",
            },
            {
                "type": "inline",
                "content": "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                "target": "/workspace/notes/readme.md",
            },
        ],
    },
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "List all files under /workspace and describe what you find.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/octocat/Spoon-Knife",
                target: "/workspace/spoon-knife",
            },
            {
                type: "gcs",
                source: "gs://cloud-samples-data/bigquery/us-states/",
                target: "/workspace/gcs-data",
            },
            {
                type: "inline",
                content: "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                target: "/workspace/notes/readme.md",
            },
        ],
    },
});

console.log(interaction.output_text);

REST

# Create interaction with sources
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "List all files under /workspace and describe what you find.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/octocat/Spoon-Knife",
                "target": "/workspace/spoon-knife"
            },
            {
                "type": "gcs",
                "source": "gs://cloud-samples-data/bigquery/us-states/",
                "target": "/workspace/gcs-data"
            },
            {
                "type": "inline",
                "content": "# Project Notes\n\n- Analyze state population data\n- Create visualizations\n",
                "target": "/workspace/notes/readme.md"
            }
        ]
    }
}'

คุณสามารถใช้ทั้ง 2 แนวทางร่วมกันได้ นั่นคือ ติดตั้งแหล่งที่มาที่ทราบแบบประกาศ จากนั้นวนซ้ำด้วยการโต้ตอบติดตามผลเพื่อติดตั้งแพ็กเกจหรือเรียกใช้สคริปต์การตั้งค่า คุณไม่สามารถตั้งค่ารูท (/) เป็นเป้าหมายเมื่อเพิ่มแหล่งที่มาที่กำหนดเองได้ คุณต้องระบุไดเรกทอรีย่อยเสมอ

ฮุก

นอกจากนี้ คุณยังติดตั้งไฟล์การกำหนดค่า .agents/hooks.json และสคริปต์การดักจับที่กำหนดเองลงในแซนด์บ็อกซ์เพื่อบังคับใช้การป้องกันด้านความปลอดภัยหรือเรียกใช้การตรวจสอบอัตโนมัติทุกครั้งที่เครื่องมือทำงานได้ด้วย ดูคำจำกัดความของสคีมาและโค้ดตัวอย่างได้ที่ ฮุก

แหล่งที่มาแบบส่วนตัว

นอกจากนี้ คุณยังดาวน์โหลดจากที่เก็บ GitHub แบบส่วนตัวหรือ Bucket ของ Cloud Storage แบบส่วนตัวได้โดยเพิ่มข้อมูลเข้าสู่ระบบในการกำหนดค่าเครือข่าย ดังนี้

สำหรับที่เก็บ Git แบบส่วนตัว ให้ใช้การตรวจสอบสิทธิ์ Basic ด้วย โทเค็นเพื่อการเข้าถึงส่วนบุคคล (PAT) ของ GitHub เข้ารหัสโทเค็นโดยใช้ x-oauth-basic เป็นชื่อผู้ใช้

echo -n "x-oauth-basic:ghp_YourPATHere" | base64

Python

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Run the test for my backend app and fix any issue.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Run the test for my backend app and fix any issue.",
    environment: {
        type: "remote",
        sources: [
            {
                type: "repository",
                source: "https://github.com/your-org/backend",
                target: "/backend-app"
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "github.com",
                    transform: {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    domain: "*"
                }
            ]
        }
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Run the test for my backend app and fix any issue.",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
}'

สำหรับBucket ของ Cloud Storage แบบส่วนตัว ให้ใช้โทเค็น Bearer ของ OAuth 2.0 มาตรฐาน

gcloud auth print-access-token

Python

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyze the discrepancies across the data in workspace",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "gs://my-private-bucket/data",
                "target": "/workspace",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "*.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    },
)

JavaScript

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Analyze the discrepancies across the data in workspace",
    environment: {
        type: "remote",
        sources: [
            {
                type: "gcs",
                source: "gs://my-private-bucket/data",
                target: "/workspace",
            }
        ],
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    domain: "*"
                }
            ]
        }
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Analyze the discrepancies across the data in workspace",
    "environment": {
        "type": "remote",
        "sources": [
            {
                "type": "gcs",
                "source": "gs://my-private-bucket/data",
                "target": "/workspace"
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer YOUR_GCS_TOKEN"
                    }
                },
                {
                    "domain": "*"
                }
            ]
        }
    }
}'

ซอฟต์แวร์ที่ติดตั้งไว้ล่วงหน้า

แซนด์บ็อกซ์ทำงานบน Ubuntu และมาพร้อมกับรันไทม์และแพ็กเกจทั่วไปที่ติดตั้งไว้ล่วงหน้า ตัวแทนสามารถติดตั้งแพ็กเกจเพิ่มเติมในรันไทม์ได้โดยใช้ pip install หรือ npm install แพ็กเกจที่ติดตั้งระหว่างการโต้ตอบจะยังคงอยู่เมื่อคุณใช้ environment_id เดียวกันซ้ำ

หมวดหมู่ แพ็กเกจที่ติดตั้งไว้ล่วงหน้า
เครื่องมือ UNIX curl, wget, git, rsync, unzip, ripgrep, fd-find, gawk, bc, tree, which, lsof, htop, jq, iproute2, procps, gcloud CLI
Python 3.12 numpy, pandas, requests, google-genai, beautifulsoup4, pyyaml, ast-grep-cli
Node.js 22 create-next-app, create-vite, typescript

การกำหนดค่าเครือข่าย

โดยค่าเริ่มต้น สภาพแวดล้อมจะมีการเข้าถึงเครือข่ายขาออกแบบไม่จำกัด ใช้ช่อง network เพื่อจำกัดการรับส่งข้อมูลขาออกไปยังโดเมนที่เฉพาะเจาะจง กฎแต่ละข้อจะระบุ domain และออบเจ็กต์ transform ที่ไม่บังคับเพื่อแทรกส่วนหัวลงในคำขอที่ตรงกัน ส่วนหัวเหล่านี้อาจไม่ซ้ำกันต่อการโต้ตอบ และคุณสามารถอัปเดตส่วนหัวสำหรับสภาพแวดล้อมเดียวกันได้

ช่อง ประเภท คำอธิบาย
domain string โดเมนที่จะจับคู่ ใช้ชื่อโฮสต์ที่แน่นอนหรือ * สำหรับโดเมนทั้งหมด
transform object ออบเจ็กต์ที่มีคู่คีย์-ค่าแบบแบนซึ่งแสดงถึงส่วนหัวที่จะแทรกลงในคำขอที่ตรงกัน เช่น {"Authorization": "Bearer ..."}

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
                {"domain": "*"},
            ]
        },
    },
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Fetch the latest issues from the GitHub API for my-org/my-repo.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "api.github.com",
                    transform: {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                { domain: "pypi.org" },
                { domain: "*" },
            ]
        }
    },
});

console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "Fetch the latest issues from the GitHub API for my-org/my-repo."}],
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    }
                },
                {"domain": "pypi.org"},
                {"domain": "*"}
            ]
        }
    }
}'

เมื่อตั้งค่ารายการที่อนุญาตไว้ ระบบจะอนุญาตเฉพาะคำขอที่ส่งไปยังโดเมนที่ระบุไว้อย่างชัดเจนเท่านั้น คุณสามารถใช้ไวลด์การ์ดเพื่อจับคู่โดเมนย่อย (เช่น {"domain": "*.example.com"}) แต่โปรดทราบว่าไวลด์การ์ดนี้จะไม่จับคู่โดเมนราก example.com ซึ่งต้องเพิ่มแยกต่างหาก หากต้องการอนุญาตการรับส่งข้อมูลอื่นๆ ทั้งหมด เช่น การกำหนดเส้นทางโดเมนที่ไม่ได้ระบุไว้โดยไม่มีส่วนหัวที่แทรก ให้เพิ่ม {"domain": "*"} เป็นรายการแบบครอบคลุม

ข้อมูลเข้าสู่ระบบ

คุณสามารถเพิ่มข้อมูลเข้าสู่ระบบเพื่อให้ตัวแทนใช้ได้โดยเพิ่มการแปลงส่วนหัว พร็อกซีขาออกจะแทรกข้อมูลเข้าสู่ระบบในส่วนหัว HTTP ที่เกี่ยวข้อง โดยข้อมูลเข้าสู่ระบบจะไม่แสดงในแซนด์บ็อกซ์เป็นตัวแปรสภาพแวดล้อมหรือไฟล์

Python

import subprocess
from google import genai

# Fetch a short-lived access token from your local gcloud CLI
gcloud_token = subprocess.check_output(
    ["gcloud", "auth", "print-access-token"], text=True
).strip()

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": f"Bearer {gcloud_token}"
                    },
                }
            ]
        },
    },
)

print(interaction.output_text)

JavaScript

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

import { execSync } from "child_process";

const gcloudToken = execSync("gcloud auth print-access-token").toString().trim();

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "List the files in gs://my-bucket/reports/ using the GCS JSON API.",
    environment: {
        type: "remote",
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": `Bearer ${gcloudToken}`
                    },
                }
            ]
        }
    },
});

console.log(