محیطها، سندباکسهای لینوکس مدیریتشدهای هستند که به عاملها مکانی ایزوله برای اجرای کد و ذخیره فایلها میدهند. آنها از زمینه تعامل جدا هستند، بنابراین میتوانید از همان محیط در چندین تعامل استفاده مجدد کنید یا در هر زمان از نو شروع کنید.
مثال زیر نحوه ایجاد تعامل با یک محیط ریموت جدید و بازیابی شناسه آن را نشان میدهد:
پایتون
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}")
جاوا اسکریپت
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}`);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Install pandas and matplotlib, verify the imports, and print the versions."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.EnvironmentID != nil {
fmt.Printf("Environment ID: %s\n", *res.Interaction.EnvironmentID)
}
}
استراحت
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 را نشان میدهند.
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// Fresh sandbox
res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Write a hello world script."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
}),
})
if err != nil {
log.Fatal(err)
}
interaction := res1.Interaction
// Reuse an existing sandbox
res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Modify the script to accept a name argument."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
PreviousInteractionID: interaction.ID,
}),
})
if err != nil {
log.Fatal(err)
}
_ = res2
// New sandbox with sources
env3 := interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeRepository.ToPointer(),
Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
Target: genai.Ptr("/workspace/spoon-knife"),
},
},
}
res3, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("List all files and summarize the project."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env3)),
}),
})
if err != nil {
log.Fatal(err)
}
_ = res3
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
}
استراحت
# 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 ذخیره کرده و دوباره از آن استفاده کنید.
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
res1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Install pandas, matplotlib, and seaborn. Verify all imports work and print the installed versions."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment("remote")),
}),
})
if err != nil {
log.Fatal(err)
}
interaction := res1.Interaction
// Reuse the configured environment
res2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Clone https://github.com/octocat/Spoon-Knife into /workspace/tools. Run the test suite and fix any missing dependencies."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
PreviousInteractionID: interaction.ID,
}),
})
if err != nil {
log.Fatal(err)
}
interaction2 := res2.Interaction
// Reuse the configured environment
res3, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Using the tools in /workspace/tools, list the files."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(*interaction.EnvironmentID)),
PreviousInteractionID: interaction2.ID,
}),
})
if err != nil {
log.Fatal(err)
}
_ = res3
if interaction.OutputText != nil {
fmt.Println(*interaction.OutputText)
}
}
استراحت
# 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"
}'
از یک منبع نصب کنید
اگر دقیقاً میدانید که عامل به چه فایلهایی نیاز دارد، میتوانید به جای تکرار، آنها را در یک فراخوانی واحد mount کنید. شیء پیکربندی environment ، آرایهای sources با سه نوع را میپذیرد:
| نوع منبع | type مقدار | توضیحات | حد |
|---|---|---|---|
| مخزن گیت | repository | یک مخزن را از یک URL در sandbox در target کپی میکند. | ۵۰۰ مگابایت |
| فضای ذخیرهسازی ابری | gcs | یک فایل یا دایرکتوری را از فضای ذخیرهسازی ابری به داخل سندباکس در target کپی میکند. | ۲ گیگابایت |
| محتوای درونخطی | inline | محتوای متنی خام را در فایلی در sandbox در target مینویسد. | ۱ مگابایت برای هر فایل، مجموعاً ۲ مگابایت |
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeRepository.ToPointer(),
Source: genai.Ptr("https://github.com/octocat/Spoon-Knife"),
Target: genai.Ptr("/workspace/spoon-knife"),
},
{
Type: interactions.SourceTypeGcs.ToPointer(),
Source: genai.Ptr("gs://cloud-samples-data/bigquery/us-states/"),
Target: genai.Ptr("/workspace/gcs-data"),
},
{
Type: interactions.SourceTypeInline.ToPointer(),
Content: genai.Ptr("# Project Notes\n\n- Analyze state population data\n- Create visualizations\n"),
Target: genai.Ptr("/workspace/notes/readme.md"),
},
},
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("List all files under /workspace and describe what you find."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
# 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"
}
]
}
}'
شما میتوانید هر دو رویکرد را با هم ترکیب کنید: منابع شناخته شده را به صورت اعلانی mount کنید، سپس با تعاملات بعدی برای نصب بستهها یا اجرای اسکریپتهای راهاندازی، تکرار کنید. هنگام افزودن یک منبع سفارشی، نمیتوانید root ( / ) را به عنوان هدف تعیین کنید، همیشه باید یک زیرشاخه مشخص کنید.
قلابها
همچنین میتوانید یک فایل پیکربندی .agents/hooks.json و اسکریپتهای رهگیری سفارشی را در sandbox نصب کنید تا گاردریلهای امنیتی را اعمال کنید یا اعتبارسنجیهای خودکار را هر زمان که ابزارها اجرا میشوند، اجرا کنید. برای تعاریف طرحواره و نمونههای کد، به Hooks مراجعه کنید.
منابع خصوصی
همچنین میتوانید با تأیید اعتبار دامنه منبع در پیکربندی شبکه، از مخازن خصوصی GitHub یا مخازن خصوصی Cloud Storage دانلود کنید.
یک گزینه، ذخیره اعتبارنامه با ارجاع توسط شناسه است، بنابراین شما رمز را یک بار ذخیره میکنید و هر محیطی که به آن منبع نیاز دارد میتواند به آن ارجاع دهد:
"network": {
"allowlist": [
{ "domain": "github.com", "credential": "github-production" },
{ "domain": "*" }
]
}
همچنین میتوانید هدر را با استفاده transform به صورت درونخطی تنظیم کنید، همانطور که در مثالهای زیر انجام میشود. پروکسی خروجی هر دو فرم را به یک شکل اعمال میکند و در هیچ یک از این دو حالت، فایل مخفی داخل جعبه شنی قرار نمیگیرد.
برای مخازن خصوصی گیت ، از احراز هویت Basic با توکن دسترسی شخصی گیتهاب (PAT) خود استفاده کنید. توکن را با استفاده از x-oauth-basic به عنوان نام کاربری رمزگذاری کنید:
echo -n "x-oauth-basic:ghp_YourPATHere" | base64
پایتون
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": "*"
}
]
}
}
)
جاوا اسکریپت
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: "*"
}
]
}
},
});
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeRepository.ToPointer(),
Source: genai.Ptr("https://github.com/your-org/backend"),
Target: genai.Ptr("/backend-app"),
},
},
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "github.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Basic YOUR_BASE64_TOKEN",
})),
},
{
Domain: "*",
},
},
}))),
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Run the test for my backend app and fix any issue."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
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": "*"
}
]
}
}
}'
برای مخازن ذخیرهسازی ابری خصوصی ، از یک توکن استاندارد OAuth 2.0 Bearer استفاده کنید:
gcloud auth print-access-token
پایتون
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": "*"
}
]
}
},
)
جاوا اسکریپت
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: "*"
}
]
}
},
});
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Sources: []interactions.Source{
{
Type: interactions.SourceTypeGcs.ToPointer(),
Source: genai.Ptr("gs://my-private-bucket/data"),
Target: genai.Ptr("/workspace"),
},
},
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "*.googleapis.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Bearer YOUR_GCS_TOKEN",
})),
},
{
Domain: "*",
},
},
}))),
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Analyze the discrepancies across the data in workspace"),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
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": "*"
}
]
}
}
}'
نرمافزارهای از پیش نصبشده
این سندباکس روی اوبونتو اجرا میشود و با زمانهای اجرا و بستههای رایج از پیش نصب شده ارائه میشود. عامل میتواند بستههای اضافی را در زمان اجرا با استفاده از pip install یا npm install نصب کند. بستههای نصب شده در طول یک تعامل، هنگام استفاده مجدد از همان environment_id ، همچنان باقی میمانند.
| دسته بندی | بستههای از پیش نصبشده |
|---|---|
| ابزارهای یونیکس | curl ، wget ، git ، rsync ، unzip ، ripgrep ، fd-find ، gawk ، bc ، tree ، which ، lsof ، htop ، jq ، iproute2 ، procps ، gcloud CLI |
| پایتون ۳.۱۲ | numpy ، pandas ، requests ، google-genai ، beautifulsoup4 ، pyyaml ، ast-grep-cli |
| نود جی اس ۲۲ | create-next-app ، create-vite ، typescript |
متغیرهای محیطی
از فیلد env برای تنظیم متغیرهای محیطی درون sandbox استفاده کنید. هر ورودی، نام یک متغیر را یا به یک رشتهی تحتاللفظی برای پیکربندی یا به یک ارجاع به یک اعتبارنامهی ذخیرهشده برای یک رمز نگاشت میکند. عامل، آنها را همانطور که در هر پوستهای میبیند، میبیند، بنابراین ابزارها و اسکریپتهایی که از محیط فرآیند میخوانند، آنها را بدون سیمکشی اضافی دریافت میکنند.
| میدان | نوع | توضیحات |
|---|---|---|
env | object | نگاشت نام متغیر به مقدار. یک مقدار یا یک string تحتاللفظی است یا یک مرجع اعتبارنامه به شکل {"credential": "credential-id"} . |
پایتون
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)
جاوا اسکریپت
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);
استراحت
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"}
}
}
}'
متغیرها به هر دستوری که عامل در آن تعامل اجرا میکند، از جمله دستورات پوسته، مراحل ساخت و هر فرآیندی که شروع میکند، اعمال میشوند.
این دو نوع مقدار رفتار متفاوتی دارند. یک رشتهی تحتاللفظی به صورت متن ساده در کانتینر نوشته میشود. ارجاع اعتبارنامه اینطور نیست: متغیر یک نگهدارندهی مکان دریافت میکند و پروکسی خروجی فقط در درخواستهای خروجی به دامنههای مورد اعتماد آن اعتبارنامه، رمز واقعی را جایگزین میکند. برای نحوهی عملکرد آن، به بخش «استفاده از اعتبارنامهها به عنوان متغیرهای محیطی» مراجعه کنید.
پیکربندی شبکه
به طور پیشفرض، محیطها دسترسی نامحدود به شبکه خروجی دارند. از فیلد network برای محدود کردن ترافیک خروجی به دامنههای خاص استفاده کنید. هر قانون یک domain را مشخص میکند، به علاوه یک credential اختیاری برای تزریق یک راز ذخیره شده و یک شیء transform اختیاری برای تزریق هدرها به درخواستهای منطبق. این هدرها میتوانند برای هر تعامل منحصر به فرد باشند و شما میتوانید آنها را برای همان محیط بهروزرسانی کنید.
| میدان | نوع | توضیحات |
|---|---|---|
domain | string | دامنه مورد نظر. از نام میزبان دقیق یا * برای همه دامنهها استفاده کنید. |
credential | string | شناسهی یک اعتبارنامهی ذخیرهشده. پروکسی خروجی آن را بررسی کرده و در زمان درخواست، هدر احراز هویت را تزریق میکند. |
transform | object | شیء حاوی جفتهای کلید-مقدار مسطح که نشاندهندهی هدرهایی برای تزریق به درخواستهای منطبق هستند، مثلاً {"Authorization": "Bearer ..."} . |
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "api.github.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Bearer ghp_your_github_token",
})),
},
{
Domain: "pypi.org",
},
{
Domain: "*",
},
},
}))),
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Fetch the latest issues from the GitHub API for my-org/my-repo."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
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": "*"}
]
}
}
}'
وقتی یک لیست مجاز تنظیم میشود، فقط درخواستها به دامنههایی که صریحاً فهرست شدهاند مجاز هستند. میتوانید از کاراکترهای جایگزین (wildcards) برای تطبیق زیر دامنهها استفاده کنید (مثلاً {"domain": "*.example.com"} )، اما توجه داشته باشید که این با دامنه ریشه example.com که باید جداگانه اضافه شود، مطابقت ندارد. برای مجاز کردن سایر ترافیکها، مانند مسیریابی دامنههای فهرست نشده بدون هدرهای تزریق شده، {"domain": "*"} را به عنوان یک ورودی catch-all اضافه کنید.
مدارک تحصیلی
دو راه برای تأیید اعتبار ترافیک خروجی وجود دارد، یک اعتبارنامه ذخیره شده که توسط ID ارجاع داده میشود و یک transform درون خطی روی قانون allowlist. پروکسی خروجی هر دو را روی سیم اعمال میکند، بنابراین در هر دو مورد، رمز هرگز وارد sandbox نمیشود و هرگز در payloadهای تعامل شما ظاهر نمیشود.
یک اعتبارنامه مدیریتشده، اعتباری است که وقتی میخواهید یک بار رمز را ذخیره کرده و دوباره از آن استفاده کنید، به آن مراجعه میکنید. هر محیط، عامل و تریگر در پروژه شما میتواند به یک شناسه مشابه ارجاع دهد و شما آن را در یک مکان میچرخانید.
پایتون
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)
جاوا اسکریپت
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);
استراحت
# 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 تنظیم کنید. این روش زمانی مناسب است که مقدار متعلق به یک فراخوانی واحد باشد، به عنوان مثال توکنی که درست قبل از ایجاد تعامل ایجاد میکنید. هدرهایی که به این روش تنظیم میشوند توسط همان پروکسی خروجی تزریق میشوند و هرگز به عنوان متغیرهای محیطی یا فایلها در داخل sandbox نمایش داده نمیشوند.
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"os/exec"
"strings"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
// Fetch a short-lived access token from your local gcloud CLI
out, err := exec.Command("gcloud", "auth", "print-access-token").Output()
if err != nil {
log.Fatal(err)
}
gcloudToken := strings.TrimSpace(string(out))
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "storage.googleapis.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Bearer " + gcloudToken,
})),
},
},
}))),
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("List the files in gs://my-bucket/reports/ using the GCS JSON API."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
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 میتوانند تحت یک قانون ظاهر شوند. credential ابتدا اعمال میشود و transform در بالا ادغام میشود، بنابراین اگر هر دو کلید یکسانی را تنظیم کنند، یک هدر transform صریح برنده میشود. یک الگوی رایج، یک credential برای هدر authentication به علاوه یک transform برای هدرهای اضافی است که سرویس در کنار آن انتظار دارد.
دسترسی به شبکه را غیرفعال کنید
برای مسدود کردن تمام دسترسیهای شبکهی خروجی، network را disabled کنید:
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
env := interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.NetworkEnumDisabled)),
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Analyze the local files only."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(env)),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
استراحت
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 روی اعتبارنامه است که هر قانون allowlist که به آن ارجاع میدهد را دست نخورده باقی میگذارد.
پایتون
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)
جاوا اسکریپت
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);
جاوا
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(""));
برو
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
// First interaction: use an initial token
initialEnv := interactions.Environment{
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "storage.googleapis.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Bearer INITIAL_TOKEN",
})),
},
},
}))),
}
firstRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("List the files in gs://my-bucket/reports/ using the GCS JSON API."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(initialEnv)),
}),
})
if err != nil {
log.Fatal(err)
}
first := firstRes.Interaction
// Later: refresh the token on the same environment
refreshedEnv := interactions.Environment{
EnvironmentID: first.EnvironmentID,
Network: genai.Ptr(interactions.NewNetwork(interactions.NewEnvironmentNetworkEgressAllowlist(interactions.Allowlist{
Allowlist: []interactions.AllowlistEntry{
{
Domain: "storage.googleapis.com",
Transform: genai.Ptr(interactions.NewTransform(map[string]string{
"Authorization": "Bearer REFRESHED_TOKEN",
})),
},
},
}))),
}
secondRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateAgentInteraction{
Agent: interactions.AgentOption("antigravity-preview-09-2026"),
Input: interactions.NewInteractionsInput("Now download the file reports/q1.csv from the same bucket."),
Environment: genai.Ptr(interactions.NewCreateAgentInteractionEnvironment(refreshedEnv)),
}),
})
if err != nil {
log.Fatal(err)
}
if secondRes.Interaction.OutputText != nil {
fmt.Println(*secondRes.Interaction.OutputText)
}
}
استراحت
# 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"
}
}
]
}
}
}'
چرخه حیات محیط زیست
محیطها از این چرخه حیات پیروی میکنند:
| ایالت | رفتار |
|---|---|
| ایجاد شده | زمانی فراهم میشود که یک تعامل، environment: "remote" یا یک شیء پیکربندی. |
| فعال | دویدن در حین انجام یک تعامل. |
| بیکار | عکس فوری خودکار و پس از ۱۵ دقیقه عدم فعالیت متوقف میشود. |
| آفلاین | از آخرین فعالیت به مدت ۷ روز نگهداری میشود. با وارد کردن شناسهاش میتوان آن را از سر گرفت. |
| حذف شده | پس از انقضای مدت زمان نگهداری TTL 7 روزه یا پس از حذف دستی، به طور خودکار از سیستم حذف میشود. |
API محیطها
شما میتوانید از API محیطها برای مدیریت برنامهریزیشدهی جلسات sandbox استفاده کنید. شمارش محیطها به شما امکان میدهد شناسههای جلسه فعال را کشف کنید و در صورت خاتمه اتصال کلاینت در طول یک کار طولانی مدت، وضعیت را بازیابی کنید. همچنین میتوانید فرادادههای جلسه را بررسی کرده و به جای انتظار برای انقضای خودکار TTL، محیطها را هنگام پایان گردشهای کاری به طور صریح حذف کنید.
فهرست کردن محیطها
محیطهای فعال متعلق به پروژه خود را فهرست کنید. از پارامترهای صفحهبندی برای کنترل اندازه دسته پاسخ استفاده کنید.
پایتون
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}")
جاوا اسکریپت
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}`);
}
جاوا
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));
}
برو
package main
import (
"context"
"fmt"
"log"
"os"
"google.golang.org/genai"
interactionssdk "google.golang.org/genai/interactions"
"google.golang.org/genai/interactions/models/components"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
}))
res, err := sdk.Environments.ListEnvironments(ctx, operations.ListEnvironmentsRequest{
PageSize: genai.Ptr(10),
})
if err != nil {
log.Fatal(err)
}
if res.ListEnvironmentsResponse != nil {
for _, env := range res.ListEnvironmentsResponse.Environments {
fmt.Printf("Environment ID: %s, Status: %v\n", env.ID, env.Status)
}
}
}
استراحت
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="
}
یک محیط دریافت کنید
بازیابی فرادادهها و جزئیات پیکربندی برای یک محیط خاص با استفاده از نام منبع آن.
پایتون
from google import genai
client = genai.Client()
env = client.environments.get(id="YOUR_ENVIRONMENT_ID")
print(f"Environment ID: {env.id}, Status: {env.status}")
جاوا اسکریپت
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}`);
جاوا
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));
برو
package main
import (
"context"
"fmt"
"log"
"os"
"google.golang.org/genai"
interactionssdk "google.golang.org/genai/interactions"
"google.golang.org/genai/interactions/models/components"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
}))
res, err := sdk.Environments.GetEnvironment(ctx, operations.GetEnvironmentRequest{
ID: "YOUR_ENVIRONMENT_ID",
})
if err != nil {
log.Fatal(err)
}
env := res.Environment
fmt.Printf("Environment ID: %s, Status: %v\n", env.ID, env.Status)
}
استراحت
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"
}
]
}
}
حذف یک محیط
به طور صریح یک محیط را خاتمه داده و حذف کنید تا منابع sandbox پس از اتمام وظایف یا pipelineهای شما پاک شوند.
پایتون
from google import genai
client = genai.Client()
client.environments.delete(id="YOUR_ENVIRONMENT_ID")
جاوا اسکریپت
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
await client.environments.delete("YOUR_ENVIRONMENT_ID");
جاوا
import com.google.genai.Client;
Client client = new Client();
client.environments.deleteEnvironment("YOUR_ENVIRONMENT_ID");
برو
package main
import (
"context"
"log"
"os"
"google.golang.org/genai"
interactionssdk "google.golang.org/genai/interactions"
"google.golang.org/genai/interactions/models/components"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
sdk := interactionssdk.New(interactionssdk.WithSecurity(components.Security{
APIKey: genai.Ptr(os.Getenv("GEMINI_API_KEY")),
}))
_, err := sdk.Environments.DeleteEnvironment(ctx, operations.DeleteEnvironmentRequest{
ID: "YOUR_ENVIRONMENT_ID",
})
if err != nil {
log.Fatal(err)
}
}
استراحت
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/environments/YOUR_ENVIRONMENT_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
مدیریت فایلها در محیط
عامل در حین اجرا، فایلها را در داخل جعبه شنی ایجاد و تغییر میدهد. شما میتوانید محتویات دایرکتوری را مرور کنید، فراداده فایل را دریافت کنید، فایلهای تکی یا کل دایرکتوریها را به صورت آرشیوهای tar دانلود کنید و فایلها را آپلود کنید یا آرشیوها را مستقیماً در محیط استخراج کنید. ذخیرهسازی در محیطهای جعبه شنی مشمول محدودیتهای استفاده منصفانه است.
فهرست کردن فایلهای موجود در یک دایرکتوری
فهرست کردن محتویات یک دایرکتوری در محیط. به طور پیشفرض، دایرکتوری ریشه را فهرست میکند.
پارامترهای پرس و جو
| پارامتر | نوع | توضیحات |
|---|---|---|
recursive | بولی | وقتی true ، تمام فایلها و دایرکتوریها را به صورت بازگشتی فهرست میکند. پیشفرض: false . |
پایتون
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}")
جاوا اسکریپت
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}`);
}
استراحت
# 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. |
دریافت متادیتای فایل
دریافت متادیتای یک فایل خاص بر اساس مسیر.
پایتون
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}")
جاوا اسکریپت
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}`);
استراحت
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 پاسخ میدهد و محتوای خام فایل را پخش میکند.
پایتون
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)
جاوا اسکریپت
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));
استراحت
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
با درخواست مسیر دایرکتوری با استفاده از ?alt=media ، کل یک دایرکتوری را به عنوان یک آرشیو tar دانلود کنید. این یک فایل tar از نوع POSIX (بدون فشردهسازی gzip) را برمیگرداند. برای اضافه کردن زیردایرکتوریهای تو در تو، recursive=true استفاده کنید.
پایتون
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")
جاوا اسکریپت
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");
استراحت
# 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} (دایرکتوری) | (هیچکدام) | false | - | - | فهرست JSON از فرزندان بلافصل |
GET /files/{path} (دایرکتوری) | (هیچکدام) | true | - | - | فهرست JSON از همه فرزندان |
GET /files/{path}?alt=media (فایل) | media | - | - | - | محتوای فایل خام |
GET /files/{path}?alt=media (دایرکتوری) | media | false | - | - | بایگانی tar فایلهای فوری در دایرکتوری |
GET /files/{path}?alt=media (دایرکتوری) | 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 در یک محیط sandbox موجود آپلود کنید. دایرکتوریهای والد در صورت عدم وجود، به طور خودکار ایجاد میشوند. ذخیرهسازی در محیطها مشمول محدودیتهای استفاده منصفانه است.
آپلود تک فایل
پایتون
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)")
جاوا اسکریپت
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)`);
استراحت
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
این پاسخ، فراداده (metadata) مربوط به فایل آپلود شده را برمیگرداند که برای هماهنگی با لیست و دریافت نقاط پایانی، در یک آرایه files قرار گرفته است:
{
"files": [
{
"name": "file.txt",
"path": "workspace/data/file.txt",
"type": "FILE",
"size_bytes": "1024",
"mime_type": "text/plain"
}
]
}
آپلود و استخراج آرشیو دایرکتوری
برای بارگذاری کل کدبیس یا ساختار دایرکتوری در یک درخواست واحد، یک فایل بایگانی .tar یا .tar.gz را با extract=true آپلود کنید.
پایتون
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}")
جاوا اسکریپت
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}`);
}
استراحت
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 برای اعلام نوع رسانه و اندازه کل payload مورد نظر برای آپلود استفاده کنید:
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 قرار میدهد. این آدرس اینترنتی از قبل حاوی 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
فایل مخرب را به صورت تکه تکه به آن 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 به شما میگوید که سرور چند بایت را commit کرده است، که در صورت عدم موفقیت یک بخش، از آنجا میتوانید ادامه دهید:
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 را تنظیم کنید (یا در REST عبارت ?overwrite=true را اضافه کنید). با extract=true ، بررسی تداخل برای هر فایل موجود در آرشیو اعمال میشود، بنابراین در صورت وجود فایل هدف، درخواست با شکست مواجه میشود.
دانلود اسنپشات کامل (منسوخ شده)
برای انتقال کد موجود به API فایلهای محیطی:
پایتون : درخواستهای دانلود فایلهای قدیمی را با موارد زیر جایگزین کنید:
archive = client.environments.files.download( environment="YOUR_ENVIRONMENT_ID", path="workspace", ) with open("snapshot.tar", "wb") as f: f.write(archive)جاوا اسکریپت : درخواستهای دانلود فایلهای قدیمی را با موارد زیر جایگزین کنید:
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
قیمتگذاری و منابع
هر محیط با تخصیص منابع ثابت اجرا میشود:
| منبع | ارزش |
|---|---|
| پردازنده | ۴ هسته |
| حافظه | ۱۶ گیگابایت |
محاسبات محیطی (پردازنده، حافظه، اجرای سندباکس) در طول دوره پیشنمایش هزینهای ندارد . برای اطلاع از هزینههای توکن عامل، به بخش قیمتگذاری مراجعه کنید.
محدودیتها
- وضعیت پیشنمایش: محیطها و عاملهای مدیریتشده در پیشنمایش هستند. ویژگیها و طرحوارهها ممکن است تغییر کنند.
- اندازه منبع درونخطی: منابع درونخطی به ۱ مگابایت برای هر فایل و ۲ مگابایت در مجموع برای همه فایلها محدود میشوند.
- اندازه منبع : مخازن گیت به ۵۰۰ مگابایت و مخازن ذخیرهسازی ابری به ۲ گیگابایت محدود شدهاند.
- راهاندازی محیط: آمادهسازی یک محیط جدید تا حدود ۵ ثانیه طول میکشد. مخازن منبع بزرگ ممکن است این زمان را افزایش دهند.
- انقضای محیط: محیطهای آفلاین غیرفعال به مدت ۷ روز قبل از انقضا با استفاده از پاکسازی خودکار TTL حفظ میشوند. وارد کردن شناسه محیط منقضی شده یا نامعتبر، خطای
404 Not Foundرا برمیگرداند. - پشتیبانی فایل: این عامل در حال حاضر محدود به خواندن فایلهای متنی و تصویری است. پشتیبانی از فایلهای باینری هنوز در دسترس نیست.
- عدم نصب از ریشه: هنگام افزودن یک منبع سفارشی، نمیتوانید ریشه (
/) را به عنوان هدف تنظیم کنید، همیشه باید یک زیرشاخه مشخص کنید.
قدم بعدی چیست؟
- مرور کلی عاملها : با مفاهیم اصلی عاملهای مدیریتشده آشنا شوید.
- شروع سریع : شروع به ساختن با مکالمات و پخش جریانی چند نوبته کنید.
- عامل ضد جاذبه : قابلیتها، ابزارها، انتخاب مدل و قیمتگذاری عامل پیشفرض را بررسی کنید.
- ساخت عاملهای سفارشی : عاملهای خودتان را با استفاده از
AGENTS.mdوSKILL.mdتعریف کنید. - قلابها : حفاظهای امنیتی را اعمال کنید و اعتبارسنجیهای جانبی را درون سندباکس اجرا کنید.