‫Interactions API זמין עכשיו לכלל המשתמשים. מומלץ להשתמש ב-API הזה כדי לקבל גישה לכל התכונות והמודלים העדכניים.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

סביבות בסוכנים מנוהלים

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

בדוגמה הבאה אפשר לראות איך ליצור אינטראקציה עם סביבה מרוחקת חדשה ולאחזר את המזהה שלה:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-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-09-2026",
    input: "Install pandas and matplotlib, verify the imports, and print the versions.",
    environment: "remote",
});

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

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Install pandas and matplotlib, verify the imports, and print the versions."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println("Environment ID: " + interaction.environmentId().orElse(""));

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-09-2026",
    "input": "Install pandas and matplotlib, verify the imports, and print the versions.",
    "environment": "remote"
}'

הפרמטר `environment`

הפרמטר environment מקבל שלוש צורות:

טופס	דוגמה	מתי להשתמש?
`"remote"`	`environment="remote"`	הקצאת ארגז חול חדש.
מזהה הסביבה	`environment="env_abc123"`	שימוש חוזר בארגז חול קיים עם כל הקבצים והחבילות שלו.
אובייקט הגדרה	`environment={...}`	הקצאת ארגז חול חדש עם מקורות, כללי רשת, משתני סביבה או שילוב שלהם.

בדוגמאות הבאות מודגם השימוש בשלוש הדרכים בפרמטר environment.

Python

from google import genai

client = genai.Client()

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

# Reuse an existing sandbox
interaction_2 = client.interactions.create(
    agent="antigravity-preview-09-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-09-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-09-2026",
    input: "Write a hello world script.",
    environment: "remote",
});

// Reuse an existing sandbox
const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-09-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-09-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

// Fresh sandbox
CreateAgentInteraction params1 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Write a hello world script."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();
Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Reuse an existing sandbox
CreateAgentInteraction params2 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Modify the script to accept a name argument."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction.id().orElse(""))
    .build();
Interaction interaction2 = client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

// New sandbox with sources
Environment env3 = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/octocat/Spoon-Knife")
            .target("/workspace/spoon-knife")
            .build()
    ))
    .build();

CreateAgentInteraction params3 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List all files and summarize the project."))
    .environment(CreateAgentInteractionEnvironment.of(env3))
    .build();
Interaction interaction3 = client.interactions.create(CreateInteractionRequestBody.of(params3)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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-09-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-09-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-09-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-09-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-09-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-09-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-09-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-09-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-09-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateAgentInteraction params1 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions."))
    .environment(CreateAgentInteractionEnvironment.of("remote"))
    .build();
Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params1)).interaction().get();

// Reuse the configured environment
CreateAgentInteraction params2 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction.id().orElse(""))
    .build();
Interaction interaction2 = client.interactions.create(CreateInteractionRequestBody.of(params2)).interaction().get();

// Reuse the configured environment
CreateAgentInteraction params3 = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Using the tools in /workspace/tools, list the files."))
    .environment(CreateAgentInteractionEnvironment.of(interaction.environmentId().orElse("")))
    .previousInteractionId(interaction2.id().orElse(""))
    .build();
Interaction interaction3 = client.interactions.create(CreateInteractionRequestBody.of(params3)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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-09-2026",
    "input": "Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions.",
    "environment": "remote"
}'

טעינה ממקור

אם אתם יודעים בדיוק אילו קבצים הסוכן צריך, כדאי להעלות אותם בקריאה אחת במקום להשתמש באיטרציה. אובייקט ההגדרה environment מקבל מערך sources עם שלושה סוגים:

סוג מקור	ערך של `type`	תיאור	מגבלה
מאגר Git	`repository`	משכפל מאגר מכתובת URL אל ארגז החול בנתיב `target`.	‫500MB
Cloud Storage	`gcs`	מעתיק קובץ או ספרייה מ-Cloud Storage אל ארגז החול בנתיב `target`.	‎2 GB
תוכן מוטבע	`inline`	כותב תוכן של טקסט גולמי לקובץ בארגז החול בנתיב `target`.	‫1MB לכל קובץ, 2MB בסך הכול

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-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-09-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/octocat/Spoon-Knife")
            .target("/workspace/spoon-knife")
            .build(),
        Source.builder()
            .type(SourceType.GCS)
            .source("gs://cloud-samples-data/bigquery/us-states/")
            .target("/workspace/gcs-data")
            .build(),
        Source.builder()
            .type(SourceType.INLINE)
            .content("# Project Notes\n\n- Analyze state population data\n- Create visualizations\n")
            .target("/workspace/notes/readme.md")
            .build()
    ))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List all files under /workspace and describe what you find."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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-09-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"
            }
        ]
    }
}'

אפשר לשלב בין שתי הגישות: להגדיר מקורות מוכרים באופן הצהרתי, ואז לחזור על הפעולות עם אינטראקציות המשך כדי להתקין חבילות או להריץ סקריפטים להגדרה. כשמוסיפים מקור בהתאמה אישית, אי אפשר להגדיר את השורש (/) כיעד, אלא תמיד צריך לציין תיקיית משנה.

תוכן מושך

אפשר גם לטעון לתוך ארגז החול .agents/hooks.json קובץ הגדרות וסקריפטים מותאמים אישית של יירוט, כדי לאכוף אמצעי הגנה או להריץ אימותים אוטומטיים בכל פעם שהכלים מופעלים. הגדרות סכמה ודוגמאות קוד מפורטות במאמר בנושא Hooks.

מקורות פרטיים

אפשר גם להוריד ממאגרי GitHub פרטיים או ממאגרי Cloud Storage פרטיים על ידי אימות דומיין המקור בהגדרות הרשת.

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

"network": {
    "allowlist": [
        { "domain": "github.com", "credential": "github-production" },
        { "domain": "*" }
    ]
}

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

בשביל מאגרי Git פרטיים, משתמשים באימות Basic עם אסימון גישה אישי (PAT) של GitHub. מבצעים קידוד של האסימון באמצעות x-oauth-basic כשם המשתמש:

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

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-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-09-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: "*"
                }
            ]
        }
    },
});

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.REPOSITORY)
            .source("https://github.com/your-org/backend")
            .target("/backend-app")
            .build()
    ))
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Basic YOUR_BASE64_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder()
                    .domain("*")
                    .build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Run the test for my backend app and fix any issue."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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

בשביל מאגרי Cloud Storage פרטיים, משתמשים באסימון Bearer רגיל מסוג OAuth 2.0:

gcloud auth print-access-token

Python

interaction = client.interactions.create(
    agent="antigravity-preview-09-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-09-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: "*"
                }
            ]
        }
    },
});

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Source;
import com.google.genai.gaos.models.interactions.SourceType;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .sources(List.of(
        Source.builder()
            .type(SourceType.GCS)
            .source("gs://my-private-bucket/data")
            .target("/workspace")
            .build()
    ))
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("*.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer YOUR_GCS_TOKEN"
                    )))
                    .build(),
                AllowlistEntry.builder()
                    .domain("*")
                    .build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the discrepancies across the data in workspace"))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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

משתני סביבה

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

שדה	סוג	תיאור
`env`	`object`	מיפוי של שם המשתנה לערך. הערך הוא או מחרוזת `string` או הפניה לפרטי כניסה מהצורה `{"credential": "credential-id"}`.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Build the project and run the test suite.",
    environment={
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "debug",
            "API_TOKEN": {"credential": "my-api-token"},
        },
    },
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Build the project and run the test suite.",
    environment: {
        type: "remote",
        env: {
            NODE_ENV: "production",
            LOG_LEVEL: "debug",
            API_TOKEN: { credential: "my-api-token" },
        },
    },
});

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-09-2026",
    "input": [{"type": "text", "text": "Build the project and run the test suite."}],
    "environment": {
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "LOG_LEVEL": "debug",
            "API_TOKEN": {"credential": "my-api-token"}
        }
    }
}'

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

יש הבדל בין שני סוגי הערכים. מחרוזת מילולית נכתבת במאגר התגים כטקסט פשוט. הפניה לפרטי כניסה היא לא: המשתנה מקבל placeholder, ושרת ה-proxy ליציאה מחליף את הסוד האמיתי רק בבקשות יוצאות לדומיינים המהימנים של פרטי הכניסה האלה. במאמר שימוש בפרטי כניסה כמשתני סביבה מוסבר איך זה עובד.

הגדרת רשת

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

שדה	סוג	תיאור
`domain`	`string`	הדומיין שצריך להתאים. צריך להשתמש בשם מארח מדויק או ב-`*` לכל הדומיינים.
`credential`	`string`	המזהה של פרטי כניסה שמורים. שרת ה-proxy ליציאה פותר את הבעיה ומחדיר את כותרת האימות בזמן הבקשה.
`transform`	`object`	אובייקט שמכיל צמדי מפתח/ערך שטוחים שמייצגים כותרות להוספה לבקשות תואמות, למשל `{"Authorization": "Bearer ..."}`.

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-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-09-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);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("api.github.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer ghp_your_github_token"
                    )))
                    .build(),
                AllowlistEntry.builder().domain("pypi.org").build(),
                AllowlistEntry.builder().domain("*").build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Fetch the latest issues from the GitHub API for my-org/my-repo."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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-09-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": "*"} כרשומה כללית.

פרטי כניסה

יש שתי דרכים לאמת תעבורת נתונים יוצאת: פרטי כניסה מאוחסנים שמקושרים למזהה, ו-transform מוטבע בכלל של רשימת ההיתרים. ה-proxy של יציאת הנתונים חל גם על החיבור, כך שבשני המקרים הסוד לא נכנס לארגז החול ולא מופיע במטענים הייעודיים (payloads) של האינטראקציה.

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

Python

from google import genai

client = genai.Client()

# Store the secret once
client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_your_github_token",
)

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

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

// Store the secret once
await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_your_github_token",
});

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

console.log(interaction.output_text);

REST

# Store the secret once
curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_your_github_token"
}'

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-09-2026",
    "input": "Fetch the latest issues from the GitHub API for my-org/my-repo.",
    "environment": {
        "type": "remote",
        "network": {
            "allowlist": [
                { "domain": "api.github.com", "credential": "github-production" },
                { "domain": "*" }
            ]
        }
    }
}'

פרטי כניסה מסוג oauth2 גם מרעננים את טוקן הגישה שלהם באופן אוטומטי, כך שאינטראקציה ארוכה לא תיפסק כשתוקף הטוקן יפוג. רשימה מלאה של סוגי האישורים ופעולות הניהול מופיעה במאמר בנושא אישורים.

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

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-09-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-09-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(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.Map;

// Fetch a short-lived access token from your local gcloud CLI
Process process = new ProcessBuilder("gcloud", "auth", "print-access-token").start();
String gcloudToken = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8).trim();

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer " + gcloudToken
                    )))
                    .build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List the files in gs://my-bucket/reports/ using the GCS JSON API."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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-09-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 <YOUR_GCLOUD_TOKEN>"
                    }
                }
            ]
        }
    }
}'

התנאים credential ו-transform יכולים להופיע באותו כלל. האישורים מוחלים קודם, ו-transform מתמזג מעל, כך שכותרת transform מפורשת מנצחת אם שניהם מגדירים את אותו מפתח. דפוס נפוץ הוא אישורים לכותרת האימות בתוספת transform לכותרות הנוספות שהשירות מצפה לקבל יחד איתה.

השבתת הגישה לרשת

כדי לחסום את כל הגישה לרשת היוצאת, מגדירים את network לערך disabled:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the local files only.",
    environment={
        "type": "remote",
        "network": "disabled",
    },
)

print(interaction.output_text)

JavaScript

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Analyze the local files only.",
    environment: {
        type: "remote",
        network: "disabled",
    },
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.NetworkEnum;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

Environment env = Environment.builder()
    .network(Network.of(NetworkEnum.DISABLED))
    .build();

CreateAgentInteraction params = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Analyze the local files only."))
    .environment(CreateAgentInteractionEnvironment.of(env))
    .build();

Interaction interaction = client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));

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-09-2026",
    "input": "Analyze the local files only.",
    "environment": {
        "type": "remote",
        "network": "disabled"
    }
}'

רענון פרטי הכניסה

תוקף של אסימונים מוטבעים, כמו אסימוני גישה ומפתחות API לטווח קצר, פג. כדי לרענן אותם, מעבירים את environment_id הקיים יחד עם הגדרה חדשה של network באינטראקציה הבאה. הכללים החדשים של הרשת מחליפים לחלוטין את הכללים הקודמים, אבל מצב מערכת הקבצים של הסביבה (חבילות מותקנות, קבצים, מאגרים) נשמר.

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

Python

from google import genai

client = genai.Client()

# First interaction: use an initial token
first = client.interactions.create(
    agent="antigravity-preview-09-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 INITIAL_TOKEN"
                    },
                }
            ]
        },
    },
)

# Later: refresh the token on the same environment
result = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Now download the file reports/q1.csv from the same bucket.",
    environment={
        "type": "remote",
        "environment_id": first.environment_id,
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    },
                }
            ]
        },
    },
)

print(result.output_text)

JavaScript

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

const client = new GoogleGenAI({});

// First interaction: use an initial token
const first = await client.interactions.create({
    agent: "antigravity-preview-09-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 INITIAL_TOKEN"
                    },
                }
            ]
        }
    },
});

// Later: refresh the token on the same environment
const result = await client.interactions.create({
    agent: "antigravity-preview-09-2026",
    input: "Now download the file reports/q1.csv from the same bucket.",
    environment: {
        type: "remote",
        environment_id: first.environment_id,
        network: {
            allowlist: [
                {
                    domain: "storage.googleapis.com",
                    transform: {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    },
                }
            ]
        }
    },
});

console.log(result.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.AgentOption;
import com.google.genai.gaos.models.interactions.Allowlist;
import com.google.genai.gaos.models.interactions.AllowlistEntry;
import com.google.genai.gaos.models.interactions.CreateAgentInteraction;
import com.google.genai.gaos.models.interactions.CreateAgentInteractionEnvironment;
import com.google.genai.gaos.models.interactions.Environment;
import com.google.genai.gaos.models.interactions.EnvironmentNetworkEgressAllowlist;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Network;
import com.google.genai.gaos.models.interactions.Transform;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.List;
import java.util.Map;

Client client = new Client();

// First interaction: use an initial token
Environment initialEnv = Environment.builder()
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer INITIAL_TOKEN"
                    )))
                    .build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction firstParams = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("List the files in gs://my-bucket/reports/ using the GCS JSON API."))
    .environment(CreateAgentInteractionEnvironment.of(initialEnv))
    .build();

Interaction first = client.interactions.create(CreateInteractionRequestBody.of(firstParams)).interaction().get();

// Later: refresh the token on the same environment
Environment refreshedEnv = Environment.builder()
    .environmentId(first.environmentId().orElse(""))
    .network(Network.of(EnvironmentNetworkEgressAllowlist.of(
        Allowlist.builder()
            .allowlist(List.of(
                AllowlistEntry.builder()
                    .domain("storage.googleapis.com")
                    .transform(Transform.of(Map.of(
                        "Authorization", "Bearer REFRESHED_TOKEN"
                    )))
                    .build()
            ))
            .build()
    )))
    .build();

CreateAgentInteraction secondParams = CreateAgentInteraction.builder()
    .agent(AgentOption.of("antigravity-preview-09-2026"))
    .input(InteractionsInput.of("Now download the file reports/q1.csv from the same bucket."))
    .environment(CreateAgentInteractionEnvironment.of(refreshedEnv))
    .build();

Interaction result = client.interactions.create(CreateInteractionRequestBody.of(secondParams)).interaction().get();
System.out.println(result.outputText().orElse(""));

REST

# Use the environment_id from a previous 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-09-2026",
    "input": "Now download the file reports/q1.csv from the same bucket.",
    "environment": {
        "type": "remote",
        "environment_id": "<ENVIRONMENT_ID_FROM_PREVIOUS_INTERACTION>",
        "network": {
            "allowlist": [
                {
                    "domain": "storage.googleapis.com",
                    "transform": {
                        "Authorization": "Bearer REFRESHED_TOKEN"
                    }
                }
            ]
        }
    }
}'

מחזור החיים של סביבה

מחזור החיים של סביבות הוא כזה:

מדינה (State)	התנהגות
נוצר	ההקצאה מתבצעת כשאינטראקציה מציינת `environment: "remote"` או אובייקט הגדרה.
פעיל	פועל בזמן שהאינטראקציה מתבצעת.
בלי פעילות	הצילום האוטומטי של התמונות יופעל וייעצר אחרי 15 דקות של חוסר פעילות.
אופליין	הנתונים נשמרים למשך 7 ימים מאז הפעילות האחרונה. אפשר להמשיך את התהליך באמצעות העברת המזהה שלו.
נמחק	הנתונים מוסרים מהמערכת באופן אוטומטי אחרי שתוקף השמירה (TTL) של 7 ימים פג, או אחרי מחיקה ידנית.

Environments API

אתם יכולים להשתמש ב-Environments API כדי לנהל באופן פרוגרמטי סשנים של ארגז חול. כשמפרטים סביבות, אפשר לגלות מזהי סשנים פעילים ולשחזר מצב אם חיבור לקוח מסתיים במהלך משימה ארוכה. אפשר גם לבדוק את המטא-נתונים של הסשן ולמחוק במפורש סביבות כשהזרימות מסתיימות, במקום לחכות שתוקף ה-TTL יפוג באופן אוטומטי.

הצגת רשימת סביבות

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

Python

from google import genai

client = genai.Client()

response = client.environments.list(page_size=10)
for env in response.environments:
    print(f"Environment ID: {env.id}, Status: {env.status}")

JavaScript

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

const client = new GoogleGenAI({});

const response = await client.environments.list({ page_size: 10 });
for (const env of response.environments) {
    console.log(`Environment ID: ${env.id}, Status: ${env.status}`);
}

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;
import com.google.genai.gaos.models.environments.ListEnvironmentsResponse;
import java.util.List;

Client client = new Client();

ListEnvironmentsResponse response = client.environments.listEnvironments()
    .pageSize(10)
    .call()
    .listEnvironmentsResponse()
    .get();

for (Environment env : response.environments().orElse(List.of())) {
    System.out.println("Environment ID: " + env.id().orElse("") + ", Status: " + env.status().orElse(null));
}

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments?pageSize=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"

התגובה אמורה להיראות כך:

{
  "environments": [
    {
      "id": "140128b2a13c12c00a5a0d8cf7af9469",
      "status": "active"
    },
    {
      "id": "362b738275a1d74af6f1c62bc050da73",
      "status": "active"
    }
  ],
  "next_page_token": "Cj...5aE="
}

קבלת סביבה

אפשר לאחזר מטא נתונים ופרטי הגדרה של סביבה ספציפית לפי שם המשאב שלה.

Python

from google import genai

client = genai.Client()

env = client.environments.get(id="YOUR_ENVIRONMENT_ID")
print(f"Environment ID: {env.id}, Status: {env.status}")

JavaScript

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

const client = new GoogleGenAI({});

const env = await client.environments.get("YOUR_ENVIRONMENT_ID");
console.log(`Environment ID: ${env.id}, Status: ${env.status}`);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.environments.Environment;

Client client = new Client();

Environment env = client.environments.getEnvironment("YOUR_ENVIRONMENT_ID").environment().get();
System.out.println("Environment ID: " + env.id().orElse("") + ", Status: " + env.status().orElse(null));

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/YOUR_ENVIRONMENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"

התגובה אמורה להיראות כך:

{
  "id": "140128b2a13c12c00a5a0d8cf7af9469",
  "status": "active",
  "sources": [
    {
      "type": "repository",
      "source": "https://github.com/octocat/Spoon-Knife",
      "target": "/workspace/spoon-knife"
    }
  ],
  "network": {
    "allowlist": [
      {
        "domain": "api.github.com"
      },
      {
        "domain": "github.com"
      }
    ]
  }
}

מחיקת סביבה

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

Python

from google import genai

client = genai.Client()

client.environments.delete(id="YOUR_ENVIRONMENT_ID")

JavaScript

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

const client = new GoogleGenAI({});

await client.environments.delete("YOUR_ENVIRONMENT_ID");

Java

import com.google.genai.Client;

Client client = new Client();

client.environments.deleteEnvironment("YOUR_ENVIRONMENT_ID");

REST

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/environments/YOUR_ENVIRONMENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"

ניהול קבצים בסביבה

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

הצגת רשימת קבצים בספרייה

הצגת רשימת התוכן של ספריה בסביבה. כברירת מחדל, מוצגת רשימה של ספריית הבסיס.

פרמטרים של שאילתה

פרמטר	סוג	תיאור
`recursive`	בוליאני	‫When `true`, lists all files and directories recursively. ברירת מחדל: `false`.

Python

from google import genai

client = genai.Client()

# List root directory
response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="",
)
for file in response.files:
    print(f"{file.name} ({file.type}) - {file.path}")

# List a subdirectory recursively
response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="src",
    recursive=True,
)
for file in response.files:
    print(f"{file.name} ({file.type}) - {file.path}")

JavaScript

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

const client = new GoogleGenAI({});

// List root directory
const response = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "",
});
for (const file of response.files) {
    console.log(`${file.name} (${file.type}) - ${file.path}`);
}

// List a subdirectory recursively
const srcResponse = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src",
    recursive: true,
});
for (const file of srcResponse.files) {
    console.log(`${file.name} (${file.type}) - ${file.path}`);
}

REST

# List root directory
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# List a subdirectory
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

# List all files recursively
curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?recursive=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

התשובה מחזירה מערך files עם מטא-נתונים לכל רשומה:

{
  "files": [
    {
      "name": "config",
      "path": "config",
      "type": "DIRECTORY",
      "created": "2026-08-12T07:44:18Z",
      "modified": "2026-08-12T07:44:18Z"
    },
    {
      "name": "main.py",
      "path": "src/main.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python; charset=utf-8",
      "created": "2026-08-12T07:44:20Z",
      "modified": "2026-08-12T07:44:20Z"
    }
  ]
}

שדות להזנת קובץ

שדה	סוג	תיאור
`name`	מחרוזת	שם הקובץ או הספרייה.
`path`	מחרוזת	הנתיב המלא ביחס לשורש הסביבה.
`type`	מחרוזת	`FILE` או `DIRECTORY`.
`size_bytes`	מחרוזת	גודל הקובץ בבייטים (קבצים בלבד).
`mime_type`	מחרוזת	סוג MIME (קבצים בלבד).
`created`	מחרוזת	חותמת הזמן של היצירה בפורמט ISO 8601.
`modified`	מחרוזת	חותמת זמן של השינוי האחרון בפורמט ISO 8601.

אחזור מטא-נתונים של קובץ

שליפת מטא-נתונים של קובץ ספציפי לפי נתיב.

Python

from google import genai

client = genai.Client()

response = client.environments.files.list(
    environment="YOUR_ENVIRONMENT_ID",
    path="src/main.py",
)
file = response.files[0]
print(f"Name: {file.name}, Size: {file.size_bytes} bytes, Type: {file.mime_type}")

JavaScript

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

const client = new GoogleGenAI({});

const response = await client.environments.files.list({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src/main.py",
});
const file = response.files[0];
console.log(`Name: ${file.name}, Size: ${file.size_bytes} bytes, Type: ${file.mime_type}`);

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src/main.py" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

התגובה מחזירה את המטא-נתונים של הקובץ עטופים במערך files:

{
  "files": [
    {
      "name": "main.py",
      "path": "src/main.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python; charset=utf-8",
      "created": "2026-08-12T07:44:20Z",
      "modified": "2026-08-12T07:44:20Z"
    }
  ]
}

אם הקובץ לא קיים, ה-API מחזיר שגיאה 404:

{
  "error": {
    "message": "Path 'nonexistent.txt' not found in environment 'ENV_ID'.",
    "code": "not_found"
  }
}

הורדת קובץ אחד

הורדת התוכן של קובץ ספציפי. ב-SDK, משתמשים בשיטה download(). בבקשות REST, מוסיפים את הפרמטר ?alt=media של השאילתה לנתיב הקובץ. השרת מגיב עם 200 OK ומזרים את תוכן הקובץ הגולמי.

Python

from google import genai

client = genai.Client()

content = client.environments.files.download(
    environment="YOUR_ENVIRONMENT_ID",
    path="src/main.py",
)

with open("main.py", "wb") as f:
    f.write(content)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const bytes = await client.environments.files.download({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src/main.py",
});

fs.writeFileSync("main.py", Buffer.from(bytes));

REST

curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src/main.py?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o main.py

הורדת ספרייה כארכיון tar

כדי להוריד ספרייה שלמה כארכיון tar, צריך לבקש את נתיב הספרייה באמצעות ?alt=media. הפונקציה מחזירה קובץ tar של POSIX (לא gzipped). כדי לכלול ספריות משנה מקוננות, משתמשים ב-recursive=true.

Python

import tarfile
from google import genai

client = genai.Client()

# Download a subdirectory archive
archive = client.environments.files.download(
    environment="YOUR_ENVIRONMENT_ID",
    path="src",
)

with open("src.tar", "wb") as f:
    f.write(archive)

with tarfile.open("src.tar") as tar:
    tar.extractall(path="./extracted")

JavaScript

import { GoogleGenAI } from "@google/genai";
import { execSync } from "child_process";
import * as fs from "fs";

const client = new GoogleGenAI({});

// Download a subdirectory archive
const bytes = await client.environments.files.download({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "src",
});

fs.writeFileSync("src.tar", Buffer.from(bytes));
execSync("tar -xf src.tar -C ./extracted");

REST

# Download a subdirectory (top-level files only)
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/src?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o src.tar

# Download a subdirectory recursively (includes nested directories)
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files/config?alt=media&recursive=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o config.tar

# Download root directory
curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o snapshot.tar

# Extract the archive
tar xf snapshot.tar -C ./extracted

מטריצת התנהגות

בטבלת ההתנהגות הבאה מפורטים התגובה הצפויה והתנהגות הארכיון בנקודות קצה של קבצים וספריות, בשיטות HTTP ובפרמטרים של שאילתות:

בקשה	`alt`	`recursive`	`extract`	`overwrite`	תשובה
`GET /files`	(ללא)	(ללא)	-	-	רשימת JSON של תיקיית השורש
`GET /files/{path}` (קובץ)	(ללא)	-	-	-	מטא-נתונים של הקובץ בפורמט JSON
`GET /files/{path}` (dir)	(ללא)	`false`	-	-	רשימת ילדים ישירים בפורמט JSON
`GET /files/{path}` (dir)	(ללא)	`true`	-	-	רשימת JSON של כל הצאצאים
`GET /files/{path}?alt=media` (קובץ)	`media`	-	-	-	תוכן גולמי של קובץ
`GET /files/{path}?alt=media` (dir)	`media`	`false`	-	-	ארכיון TAR של קבצים מיידיים בספרייה
`GET /files/{path}?alt=media` (dir)	`media`	`true`	-	-	ארכיון TAR של כל הקבצים באופן רקורסיבי
`GET /files?alt=media`	`media`	`false`	-	-	ארכיון TAR של קבצים ברמת הבסיס בלבד
`PUT /files/{path}` (קובץ)	-	-	`false`	`false`	כותב את הקובץ בנתיב. מחזירה `409 Conflict` אם היא כבר קיימת
`PUT /files/{path}?overwrite=true`	-	-	`false`	`true`	כתיבה או החלפה של הקובץ בנתיב
`PUT /files/{path}?extract=true`	-	-	`true`	`false`	הארכיון נפרק לספריית היעד. הפונקציה מחזירה את הערך `409 Conflict` אם קיים קובץ יעד כלשהו
`PUT /files/{path}?extract=true&overwrite=true`	-	-	`true`	`true`	פירוק הארכיון והחלפת קבצים קיימים

העלאת קבצים לסביבה

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

העלאת קובץ אחד

Python

from google import genai

client = genai.Client()

with open("local_file.txt", "rb") as f:
    result = client.environments.files.upload(
        environment="YOUR_ENVIRONMENT_ID",
        path="workspace/data/file.txt",
        file=f,
        mime_type="text/plain",
        overwrite=True,
    )

file = result.files[0]
print(f"Uploaded: {file.name} ({file.size_bytes} bytes)")

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const content = fs.readFileSync("local_file.txt");
const result = await client.environments.files.upload({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "workspace/data/file.txt",
    file: content,
    mime_type: "text/plain",
    overwrite: true,
});

const file = result.files[0];
console.log(`Uploaded: ${file.name} (${file.size_bytes} bytes)`);

REST

curl -X PUT "https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/data/file.txt" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @local_file.txt

התגובה מחזירה מטא-נתונים של הקובץ שהועלה, עטופים במערך files כדי לשמור על עקביות עם נקודות הקצה של list ו-get:

{
  "files": [
    {
      "name": "file.txt",
      "path": "workspace/data/file.txt",
      "type": "FILE",
      "size_bytes": "1024",
      "mime_type": "text/plain"
    }
  ]
}

העלאה וחילוץ של ארכיון ספריות

כדי להזין קוד בסיס או מבנה ספריות שלמים בבקשה אחת, מעלים ארכיון .tar או .tar.gz באמצעות extract=true.

Python

from google import genai

client = genai.Client()

with open("source.tar.gz", "rb") as f:
    result = client.environments.files.upload(
        environment="YOUR_ENVIRONMENT_ID",
        path="workspace/src/",
        file=f,
        extract=True,
    )

for entry in result.files:
    print(f"Extracted: {entry.path}")

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const client = new GoogleGenAI({});

const archive = fs.readFileSync("source.tar.gz");
const result = await client.environments.files.upload({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "workspace/src/",
    file: archive,
    extract: true,
});

for (const entry of result.files) {
    console.log(`Extracted: ${entry.path}`);
}

REST

curl -X PUT "https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/src/?extract=true" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/x-tar" \
  --data-binary @source.tar.gz

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

{
  "files": [
    {
      "name": "app.py",
      "path": "workspace/src/app.py",
      "type": "FILE",
      "size_bytes": "15",
      "mime_type": "text/x-python"
    },
    {
      "name": "requirements.txt",
      "path": "workspace/src/requirements.txt",
      "type": "FILE",
      "size_bytes": "17",
      "mime_type": "text/plain"
    }
  ]
}

העלאת קבצים גדולים באמצעות סשן שניתן להמשיך

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

מתחילים בהפעלת הסשן עם uploadType=resumable. שולחים גוף ריק ומשתמשים בכותרות X-Upload-Content-Type ו-X-Upload-Content-Length כדי להצהיר על סוג המדיה והגודל הכולל של מטען הייעודי שרוצים להעלות:

PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable HTTP/1.1
Host: generativelanguage.googleapis.com
X-Upload-Content-Type: application/octet-stream
X-Upload-Content-Length: 20971520
Content-Length: 0
x-goog-api-key: $GEMINI_API_KEY

כתובת ה-URL של הסשן מופיעה בתגובה בכותרת Location. כתובת ה-URL הזו כבר מכילה את upload_id, ולכן לא צריך להוסיף אליה שוב את מפתח ה-API:

HTTP/1.1 200 OK
Location: https://generativelanguage.googleapis.com/upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY
Content-Length: 0

מעלים את מטען הייעודי (payload) לכתובת ה-URL הזו במקטעים. כל נתח מציין את טווח הבייטים שלו ואת הגודל הכולל באמצעות כותרת Content-Range:

PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY HTTP/1.1
Host: generativelanguage.googleapis.com
Content-Type: application/octet-stream
Content-Range: bytes 0-10485759/20971520
Content-Length: 10485760

<10 MB binary payload>

כל נתח, חוץ מהאחרון, מחזיר 308 Resume Incomplete. הכותרת Range מציינת כמה בייטים השרת אישר, וזה המקום שממנו צריך לחדש את ההעלאה אם נתקלנו בבעיה עם נתח:

HTTP/1.1 308 Resume Incomplete
Range: bytes=0-10485759
Content-Length: 0

שולחים את שאר החלקים באותה דרך:

PUT /upload/v1beta/environments/$ENV_ID/files/workspace/data/large_dataset.bin?uploadType=resumable&upload_id=AJjja9bfHjiYlGi60pUazCaTuPY HTTP/1.1
Host: generativelanguage.googleapis.com
Content-Type: application/octet-stream
Content-Range: bytes 10485760-20971519/20971520
Content-Length: 10485760

<remaining 10 MB binary payload>

המקטע האחרון משלים את ההעלאה ומחזיר את המטא-נתונים של הקובץ, באותו מעטפת files כמו בהעלאה חד-פעמית:

{
  "files": [
    {
      "name": "large_dataset.bin",
      "path": "workspace/data/large_dataset.bin",
      "type": "FILE",
      "size_bytes": "20971520",
      "mime_type": "application/octet-stream"
    }
  ]
}

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

הגנה מפני החלפה

כברירת מחדל, הערך של overwrite הוא false. אם נתיב היעד כבר קיים, הבקשה מחזירה שגיאה 409 Conflict ולא נכתב דבר:

{
  "error": {
    "message": "Requested entity already exists",
    "code": "aborted"
  }
}

כדי להחליף קובץ או ספרייה קיימים, מגדירים את overwrite=true (או מוסיפים ?overwrite=true ב-REST). בשימוש ב-extract=true, בדיקת ההתנגשות חלה על כל קובץ בארכיון, ולכן הבקשה נכשלת אם קיים קובץ יעד כלשהו.

הורדת תמונת מצב מלאה (הוצא משימוש)

כדי להעביר קוד קיים אל Environment Files API:

‫Python: מחליפים את בקשות ההורדה של קבצים מדור קודם בבקשות הבאות:

archive = client.environments.files.download(
    environment="YOUR_ENVIRONMENT_ID",
    path="workspace",
)
with open("snapshot.tar", "wb") as f:
    f.write(archive)

‫JavaScript: מחליפים את בקשות ההורדה של קבצים מדור קודם בבקשות הבאות:

const bytes = await client.environments.files.download({
    environment: "YOUR_ENVIRONMENT_ID",
    path: "workspace",
});
fs.writeFileSync("snapshot.tar", Buffer.from(bytes));

‫REST: מחליפים את GET /v1beta/files/environment-$ENV_ID:download?alt=media ב:

curl -L -X GET "https://generativelanguage.googleapis.com/v1beta/environments/$ENV_ID/files?alt=media" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -o snapshot.tar

מחירים ומשאבים

כל סביבה פועלת עם הקצאות משאבים קבועות:

משאב	ערך
CPU	‫4 ליבות
זיכרון	‫16GB

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

מגבלות

סטטוס התצוגה המקדימה: סביבות ונציגים מנוהלים נמצאים בתצוגה מקדימה. יכולים להיות שינויים בתכונות ובסכימות.
גודל מקור מוטבע: הגודל המקסימלי של מקורות מוטבעים הוא 1MB לכל קובץ, ו-2MB בסך הכול בכל הקבצים.
גודל המקור: מאגרי Git מוגבלים ל-500MB ומאגרי Cloud Storage מוגבלים ל-2GB.
הפעלת הסביבה: הקצאת סביבה חדשה נמשכת עד 5 שניות. אם מאגרי המקור גדולים, יכול להיות שהזמן הזה יתארך.
תפוגה של סביבה: סביבות אופליין לא פעילות נשמרות למשך 7 ימים לפני שהן מתפוגות באמצעות ניקוי אוטומטי של TTL. העברה של מזהה סביבה שפג תוקפו או שהוא לא תקין מחזירה שגיאת 404 Not Found.
תמיכה בקבצים: בשלב הזה, הסוכן מוגבל לקריאת קובצי טקסט ותמונות. עדיין אין תמיכה בקבצים בינאריים.
אי אפשר לבצע הרכבה מהשורש: אי אפשר להגדיר את השורש (/) כיעד כשמוסיפים מקור מותאם אישית, ותמיד צריך לציין תת-ספרייה.

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

סקירה כללית על סוכנים: מידע על המושגים המרכזיים של סוכנים מנוהלים.
מדריך למתחילים: איך מתחילים ליצור שיחות רב-שלביות וסטרימינג.
‫Antigravity Agent: מידע על היכולות, הכלים, בחירת המודל והתמחור של הסוכן שמוגדר כברירת מחדל.
יצירת סוכנים בהתאמה אישית: הגדרת סוכנים משלכם באמצעות AGENTS.md ו-SKILL.md.
Hooks: אכיפת שכבות הגנה והרצת אימותים של תופעות לוואי בתוך ארגז החול.

סביבות בסוכנים מנוהלים

Python

JavaScript

Java

REST

הפרמטר environment

Python

JavaScript

Java

REST

הגדרת סביבה

Python

JavaScript

Java

REST

טעינה ממקור

Python

JavaScript

Java

REST

תוכן מושך

מקורות פרטיים

Python

JavaScript

Java

REST

Python

JavaScript

Java

REST

תוכנה שהותקנה מראש

משתני סביבה

Python

JavaScript

REST

הגדרת רשת

Python

JavaScript

Java

REST

פרטי כניסה

Python

JavaScript

REST

Python

JavaScript

Java

REST

השבתת הגישה לרשת

Python

JavaScript

Java

REST

רענון פרטי הכניסה

Python

JavaScript

Java

REST

מחזור החיים של סביבה

Environments API

הצגת רשימת סביבות

Python

JavaScript

Java

REST

קבלת סביבה

Python

JavaScript

Java

REST

מחיקת סביבה

Python

JavaScript

Java

REST

ניהול קבצים בסביבה

הצגת רשימת קבצים בספרייה

פרמטרים של שאילתה

Python

JavaScript

הפרמטר `environment`