عامل ضد جاذبه

عامل Antigravity یک عامل مدیریت‌شده‌ی همه‌منظوره در رابط برنامه‌نویسی Gemini است. یک فراخوانی API به شما عاملی می‌دهد که در داخل جعبه‌ی شنی امن لینوکس شما که توسط گوگل میزبانی می‌شود، استدلال می‌کند، کد را اجرا می‌کند، فایل‌ها را مدیریت می‌کند و وب را مرور می‌کند.

این برنامه توسط Gemini 3.5 Flash پشتیبانی می‌شود و از همان سیستم عامل Antigravity IDE استفاده می‌کند. از طریق Interactions API و Google AI Studio در دسترس است.

پایتون

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    environment="remote",
)

print(interaction.output_text)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    environment: "remote",
}, { timeout: 300000 });

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-05-2026",
    "input": "Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
    "environment": "remote"
}'

قابلیت‌ها

هر تماس می‌تواند یک سندباکس لینوکس را فراهم کند و یک حلقه استفاده از ابزار را آغاز کند. عامل برنامه‌ریزی می‌کند، عمل می‌کند، نتایج را مشاهده می‌کند و تا زمانی که کار انجام شود، تکرار می‌کند.

  • اجرای کد: اجرای دستورات Bash، Python و Node.js. نصب بسته‌ها، اجرای تست‌ها، ساخت برنامه‌ها.
  • مدیریت فایل: خواندن، نوشتن، ویرایش، جستجو و فهرست کردن فایل‌ها در محیط سندباکس. فایل‌ها در تعاملات مختلف باقی می‌مانند.
  • دسترسی به وب: جستجوی گوگل و دریافت داده‌ها از طریق URL.
  • فشرده‌سازی متن: فشرده‌سازی خودکار متن (در حدود ۱۳۵ هزار توکن فعال می‌شود) برای پشتیبانی از جلسات طولانی مدت و چند نوبتی بدون از دست دادن متن یا رسیدن به محدودیت‌های توکن.

برای استفاده چند نوبتی و پخش جریانی، به شروع سریع مراجعه کنید.

ابزارهای پشتیبانی شده

به طور پیش‌فرض، عامل به code_execution ، google_search و url_context دسترسی دارد. ابزارهای سیستم فایل به طور خودکار هنگام تعیین پارامتر environment فعال می‌شوند. همچنین می‌توانید توابع سفارشی را برای اتصال عامل به APIها و ابزارهای خود تعریف کنید. فقط هنگام سفارشی‌سازی یا محدود کردن مجموعه پیش‌فرض یا هنگام اضافه کردن توابع سفارشی، باید پارامتر tools را مشخص کنید.

ابزار مقدار نوع توضیحات
اجرای کد code_execution اجرای دستورات پوسته (bash، Python، Node) با ضبط stdout/stderr.
جستجوی گوگل google_search در وب عمومی جستجو کنید.
متن URL url_context صفحات وب را دریافت و مطالعه کنید.
سیستم فایل (از طریق environment فعال می‌شود) خواندن، نوشتن، ویرایش، جستجو و فهرست کردن فایل‌ها در محیط سندباکس. بدون نوع ابزار جداگانه؛ با تنظیم environment ، به‌طور خودکار فعال می‌شود.
توابع سفارشی function توابع سفارشی را تعریف کنید که عامل می‌تواند درخواست اجرای آنها را داشته باشد. به فراخوانی تابع مراجعه کنید.
سرور MCP از راه دور mcp_server سرورهای پروتکل زمینه مدل (MCP) خارجی را به عنوان ابزار ثبت کنید. به سرورهای MCP مراجعه کنید.

برای محدود کردن عامل به ابزارهای خاص، فقط ابزارهای مورد نیاز خود را ارسال کنید:

پایتون

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Search for the latest AI research papers on reasoning and summarize them.",
    environment="remote",
    tools=[
        {"type": "google_search"},
        {"type": "url_context"},
    ],
)

print(interaction.output_text)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Search for the latest AI research papers on reasoning and summarize them.",
    environment: "remote",
    tools: [
        { type: "google_search" },
        { type: "url_context" },
    ],
}, { timeout: 300000 });

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-05-2026",
    "input": "Search for the latest AI research papers on reasoning and summarize them.",
    "environment": "remote",
    "tools": [
        {"type": "google_search"},
        {"type": "url_context"}
    ]
}'

ورودی چندوجهی

عامل Antigravity از ورودی‌های چندوجهی پشتیبانی می‌کند. در حال حاضر، فقط ورودی‌های text و image پشتیبانی می‌شوند. تصاویر باید به صورت رشته‌های ( data ) کدگذاری شده با base64 درون‌خطی ارائه شوند.

پایتون

import base64
from google import genai

client = genai.Client()

with open("path/to/chart.png", "rb") as f:
    image_bytes = f.read()

interaction_inline = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input=[
        {"type": "text", "text": "Analyze this chart and summarize the trends."},
        {
            "type": "image",
            "data": base64.b64encode(image_bytes).decode("utf-8"),
            "mime_type": "image/png",
        },
    ],
    environment="remote",
)

جاوا اسکریپت


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

import * as fs from "node:fs";

const client = new GoogleGenAI({});
const base64Image = fs.readFileSync("path/to/chart.png", { encoding: "base64" });

const interactionInline = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: [
        { type: "text", text: "Analyze this chart and summarize the trends." },
        {
            type: "image",
            data: base64Image,
            mime_type: "image/png",
        },
    ],
    environment: "remote",
}, { timeout: 300000 });

استراحت

BASE64_IMAGE=$(base64 -w0 /path/to/chart.png)

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d "{
    \"agent\": \"antigravity-preview-05-2026\",
    \"input\": [
        {\"type\": \"text\", \"text\": \"Analyze this chart and summarize the trends.\"},
        {
            \"type\": \"image\",
            \"mime_type\": \"image/png\",
            \"data\": \"$BASE64_IMAGE\"
        }
    ],
    \"environment\": \"remote\"
}"

فراخوانی تابع

فراخوانی تابع به شما این امکان را می‌دهد که با تعریف ابزارهای سفارشی که عامل می‌تواند فراخوانی کند، عامل Antigravity را به APIها و پایگاه‌های داده خارجی متصل کنید. برای مفاهیم کلی، به فراخوانی تابع با API Gemini مراجعه کنید.

مثال زیر یک تعامل دو نوبتی را نشان می‌دهد. ابتدا عامل یک فراخوانی تابع سفارشی get_weather را درخواست می‌کند و کلاینت آن را اجرا کرده و نتیجه را در نوبت دوم برمی‌گرداند.

پایتون

from google import genai

client = genai.Client()

# 1. Define the custom function
get_weather_tool = {
    "type": "function",
    "name": "get_weather",
    "description": "Gets the current weather for a given location.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, e.g. San Francisco, USA",
            }
        },
        "required": ["location"],
    },
}

# 2. Call the agent with the custom tool (Turn 1)
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[
        {"type": "code_execution"},  # Enable default code execution
        get_weather_tool,            # Add custom function
    ],
)

# Check if the agent requested a function call
if interaction.status == "requires_action":
    # Find function calls that do not have a matching function result.
    # Filesystem tools (like write_file) are also represented as function calls
    # but are executed automatically by the environment.
    executed_calls = {step.call_id for step in interaction.steps if step.type == "function_result"}
    pending_calls = [step for step in interaction.steps if step.type == "function_call" and step.id not in executed_calls]

    if pending_calls:
        fc_step = pending_calls[0]
        print(f"Function to call: {fc_step.name} (ID: {fc_step.id})")
        print(f"Arguments: {fc_step.arguments}")

        # 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
        function_result = {
            "temperature": 23,
            "unit": "celsius"
        }

        final_interaction = client.interactions.create(
            agent="antigravity-preview-05-2026",
            previous_interaction_id=interaction.id,  # Reference the interaction ID
            environment=interaction.environment_id,
            input=[
                {
                    "type": "function_result",
                    "name": fc_step.name,
                    "call_id": fc_step.id,
                    "result": function_result,
                }
            ],
        )

        print(final_interaction.output_text)
        # Output: The current weather in Tokyo, Japan is 23°C (Celsius).
    else:
        print("No pending function calls.")
else:
    print(f"Interaction completed with status: {interaction.status}")

جاوا اسکریپت

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

const client = new GoogleGenAI({});

// 1. Define the custom function
const get_weather_tool = {
  type: "function",
  name: "get_weather",
  description: "Gets the current weather for a given location.",
  parameters: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "The city and country, e.g. San Francisco, USA",
      },
    },
    required: ["location"],
  },
};

// 2. Call the agent with the custom tool (Turn 1)
const interaction = await client.interactions.create({
  agent: "antigravity-preview-05-2026",
  input: "What is the weather in Tokyo?",
  environment: "remote",
  tools: [
    { type: "code_execution" },
    get_weather_tool,
  ],
}, { timeout: 300000 });

if (interaction.status === "requires_action") {
  // Find function calls that do not have a matching function result.
  // Filesystem tools (like write_file) are also represented as function calls
  // but are executed automatically by the environment.
  const executedCalls = new Set(
    interaction.steps
      .filter(s => s.type === "function_result")
      .map(s => s.call_id)
  );
  const pendingCalls = interaction.steps.filter(
    s => s.type === "function_call" && !executedCalls.has(s.id)
  );

  if (pendingCalls.length > 0) {
    const fcStep = pendingCalls[0];
    console.log(`Function to call: ${fcStep.name} (ID: ${fcStep.id})`);

    // 3. Execute the function locally (simulated get_weather()) and send the result back (Turn 2)
    const functionResult = {
      temperature: 23,
      unit: "celsius"
    };

    const finalInteraction = await client.interactions.create({
      agent: "antigravity-preview-05-2026",
      previous_interaction_id: interaction.id, // Reference the interaction ID
      environment: interaction.environment_id,
      input: [
        {
          type: "function_result",
          name: fcStep.name,
          call_id: fcStep.id,
          result: functionResult,
        }
      ],
    }, { timeout: 300000 });

    console.log(finalInteraction.output_text);
  } else {
    console.log("No pending function calls.");
  }
} else {
  console.log(`Interaction completed with status: ${interaction.status}`);
}

استراحت

# 1. Turn 1: Request function call
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "agent": "antigravity-preview-05-2026",
      "input": "What is the weather in Tokyo?",
      "environment": "remote",
      "tools": [
          {"type": "code_execution"},
          {
              "type": "function",
              "name": "get_weather",
              "description": "Gets the current weather for a given location.",
              "parameters": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"}
                  },
                  "required": ["location"]
              }
          }
      ]
  }')

# Extract interaction ID, environment ID, and call ID (requires jq)
INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')
ENVIRONMENT_ID=$(echo $RESPONSE | jq -r '.environment_id')
CALL_ID=$(echo $RESPONSE | jq -r '.steps[] | select(.type=="function_call") | .id')

# 2. Turn 2: Send function result back using variables
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d "{
      \"agent\": \"antigravity-preview-05-2026\",
      \"previous_interaction_id\": \"$INTERACTION_ID\",
      \"environment\": \"$ENVIRONMENT_ID\",
      \"input\": [
          {
              \"type\": \"function_result\",
              \"name\": \"get_weather\",
              \"call_id\": \"$CALL_ID\",
              \"result\": {
                  \"temperature\": 23,
                  \"unit\": \"celsius\"
              }
          }
      ]
  }"

سرورهای MCP

شما می‌توانید با ثبت سرورهای پروتکل زمینه مدل (MCP) از راه دور، عامل Antigravity را به ابزارهای خارجی متصل کنید. این عامل از سرورهای MCP از راه دور از طریق HTTP قابل پخش پشتیبانی می‌کند.

هنگام ثبت سرور MCP، باید فیلدهای زیر را در آرایه tools مشخص کنید:

میدان نوع مورد نیاز توضیحات
type رشته بله باید "mcp_server" باشد.
name رشته بله یک شناسه منحصر به فرد برای سرور. باید کاملاً با حروف کوچک و حروف الفبا و عدد باشد (مطابق با ^[a-z0-9_-]+$ ).
url رشته بله آدرس اینترنتی (URL) نقطه پایانی سرور MCP از راه دور.
headers شیء خیر هدرهای سفارشی (مثلاً احراز هویت) همراه با درخواست‌ها ارسال می‌شوند.
allowed_tools آرایه خیر فهرست نام ابزارهای مجاز برای اجرا. در صورت حذف، همه ابزارها مجاز هستند.

پایتون

from google import genai

client = genai.Client()

# Register a remote HTTP MCP server
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="What is the weather in Tokyo?",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "weather", # Must be lowercase
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
    }]
)

print(interaction.output_text)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "What is the weather in Tokyo?",
    environment: "remote",
    tools: [{
        type: "mcp_server",
        name: "weather", // Must be lowercase
        url: "https://gemini-api-demos.uc.r.appspot.com/mcp"
    }]
}, { timeout: 300000 });

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-05-2026",
      "input": "What is the weather in Tokyo?",
      "environment": "remote",
      "tools": [{
          "type": "mcp_server",
          "name": "weather",
          "url": "https://gemini-api-demos.uc.r.appspot.com/mcp"
      }]
  }'

سفارشی‌سازی عامل

شما می‌توانید عامل Antigravity را با سفارشی‌سازی دستورالعمل‌ها، ابزارها و محیط آن گسترش دهید. این عامل از رویکرد بومی سیستم فایل برای سفارشی‌سازی پشتیبانی می‌کند: می‌توانید فایل‌هایی مانند AGENTS.md را برای دستورالعمل‌ها و مهارت‌ها تحت .agents/skills/ مستقیماً در sandbox مانت کنید، یا پیکربندی را به صورت درون‌خطی در زمان تعامل منتقل کنید. می‌توانید پیکربندی خود را به صورت درون‌خطی تکرار کنید و سپس وقتی آماده شدید، آن را به عنوان یک عامل مدیریت‌شده ذخیره کنید.

برای جزئیات کامل در مورد نحوه ساخت عامل‌های سفارشی، به بخش «ساخت عامل‌های مدیریت‌شده» مراجعه کنید.

اجرای پس‌زمینه

وظایف عامل که شامل استدلال چند مرحله‌ای، اجرای کد یا عملیات فایل هستند، می‌توانند چند دقیقه طول بکشند. برای اجرای ناهمگام تعامل background=True استفاده کنید. API بلافاصله یک شناسه تعامل را برمی‌گرداند که تا زمان completed یا failed وضعیت، آن را بررسی می‌کنید.

پایتون

import time
from google import genai

client = genai.Client()

# 1. Start the interaction in the background
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Run a complex analysis on the repository.",
    environment="remote",
    background=True,
)

print(f"Interaction started in background: {interaction.id}")

# 2. Poll for completion
while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

if interaction.status == "completed":
    print(interaction.output_text)
else:
    print(f"Finished with status: {interaction.status}")

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Run a complex analysis on the repository.",
    environment: "remote",
    background: true,
});

console.log(`Interaction started in background: ${interaction.id}`);

let result = interaction;
while (result.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    result = await client.interactions.get(interaction.id);
}

if (result.status === "completed") {
    console.log(result.output_text);
} else {
    console.log(`Finished with status: ${result.status}`);
}

استراحت

# 1. Start the interaction in the background
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "antigravity-preview-05-2026",
      "input": "Run a complex analysis on the repository.",
      "environment": "remote",
      "background": true
  }')

INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Poll for results (repeat until status is "completed")
curl -s -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

اجرای پس‌زمینه نیاز به store=True دارد که پیش‌فرض است. برای به‌روزرسانی‌های پیشرفت بلادرنگ در حین اجرای پس‌زمینه، به Streaming background interactions مراجعه کنید.

شما می‌توانید با استفاده از متد cancel ، یک تعامل در حال اجرا در پس‌زمینه را لغو کنید.

پایتون

client.interactions.cancel(id="INTERACTION_ID")

جاوا اسکریپت

await client.interactions.cancel("INTERACTION_ID");

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions/INTERACTION_ID:cancel" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

چند نوبتی با اجرای پس زمینه

وقتی یک تعامل پس‌زمینه شامل ابزارهای دارای وضعیت (مانند اجرای کد در یک جعبه شنی) است، از environment_id مربوط به تعامل تکمیل‌شده برای ادامه در همان محیط استفاده کنید. این کار تضمین می‌کند که عامل از جایی که متوقف شده بود، با تمام فایل‌ها و وضعیت دست‌نخورده، ادامه می‌دهد.

پایتون

import time
from google import genai

client = genai.Client()

# First turn: run a task in the background
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Clone https://github.com/google/generative-ai-python and run its tests.",
    environment="remote",
    background=True,
)

while interaction.status == "in_progress":
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

# Second turn: continue in the same environment
followup = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Fix any failing tests and re-run them.",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    background=True,
)

while followup.status == "in_progress":
    time.sleep(5)
    followup = client.interactions.get(id=followup.id)

print(followup.output_text)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

// First turn: run a task in the background
let interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Clone https://github.com/google/generative-ai-python and run its tests.",
    environment: "remote",
    background: true,
});

while (interaction.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    interaction = await client.interactions.get(interaction.id);
}

// Second turn: continue in the same environment
let followup = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Fix any failing tests and re-run them.",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    background: true,
});

while (followup.status === "in_progress") {
    await new Promise(resolve => setTimeout(resolve, 5000));
    followup = await client.interactions.get(followup.id);
}

console.log(followup.output_text);

استراحت

# 1. Start first interaction in the background
RESPONSE=$(curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "agent": "antigravity-preview-05-2026",
      "input": "Clone https://github.com/google/generative-ai-python and run its tests.",
      "environment": "remote",
      "background": true
  }')

INTERACTION_ID=$(echo $RESPONSE | jq -r '.id')

# 2. Poll until completed (repeat until status is "completed")
RESULT=$(curl -s -X GET "https://generativelanguage.googleapis.com/v1beta/interactions/$INTERACTION_ID" \
  -H "x-goog-api-key: $GEMINI_API_KEY")

ENVIRONMENT_ID=$(echo $RESULT | jq -r '.environment_id')

# 3. Continue in the same environment
curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d "{
      \"agent\": \"antigravity-preview-05-2026\",
      \"input\": \"Fix any failing tests and re-run them.\",
      \"previous_interaction_id\": \"$INTERACTION_ID\",
      \"environment\": \"$ENVIRONMENT_ID\",
      \"background\": true
  }"

محیط‌ها

هر فراخوانی یک سندباکس لینوکس ایجاد یا دوباره استفاده می‌کند. پارامتر environment سه شکل دارد:

فرم توضیحات
"remote" یک سندباکس جدید با تنظیمات پیش‌فرض فراهم کنید.
"env_abc123" استفاده مجدد از یک محیط موجود بر اساس شناسه، با حفظ تمام فایل‌ها و وضعیت.
{...} پیکربندی کامل EnvironmentConfig با منابع سفارشی و قوانین شبکه.

برای جزئیات بیشتر در مورد منابع (Git، GCS، درون‌خطی)، شبکه‌سازی، چرخه حیات و محدودیت‌های منابع، به بخش محیط‌ها مراجعه کنید.

محرک‌ها

تریگرها به شما امکان می‌دهند یک عامل را برای اجرای خودکار در یک برنامه‌ی cron زمان‌بندی کنید. یک تریگر، یک عامل، محیط، اعلان و زمان‌بندی را به یک منبع پایدار متصل می‌کند که بدون دخالت دستی اجرا می‌شود. هر اجرا از همان محیط استفاده مجدد می‌کند، بنابراین فایل‌های ایجاد شده در یک اجرا باقی می‌مانند و برای اجراهای بعدی قابل مشاهده هستند.

یک تریگر ایجاد کنید

با مشخص کردن برنامه cron، منطقه زمانی و پیکربندی تعامل، یک trigger ایجاد کنید. trigger در وضعیت active شروع به کار می‌کند و در زمان cron بعدی مطابق با آن فعال می‌شود. id بازگشتی را برای مدیریت trigger در فراخوانی‌های بعدی ذخیره کنید.

پایتون

from google import genai

client = genai.Client()

trigger = client.triggers.create(
    schedule="0 9 * * *",
    time_zone="America/Argentina/Buenos_Aires",
    display_name="issue-solver",
    interaction={
        "agent": "antigravity-preview-05-2026",
        "input": "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/.",
        "environment": {
            "type": "remote",
            "network": {
                "allowlist": [
                    {
                        "domain": "api.github.com",
                        "transform": {
                            "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                        },
                    },
                    {"domain": "github.com"},
                ]
            },
        },
    },
)

print(f"Trigger created: {trigger.id}")
print(f"Next run: {trigger.next_run_time}")

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const trigger = await client.triggers.create({
    schedule: "0 9 * * *",
    time_zone: "America/Argentina/Buenos_Aires",
    display_name: "issue-solver",
    interaction: {
        agent: "antigravity-preview-05-2026",
        input: [{
            type: "text",
            text: "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled 'accepted', skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/.",
        }],
        environment: {
            type: "remote",
            network: {
                allowlist: [
                    {
                        domain: "api.github.com",
                        transform: {
                            "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                        },
                    },
                    { domain: "github.com" },
                ],
            },
        },
    },
});

console.log(`Trigger created: ${trigger.id}`);
console.log(`Next run: ${trigger.next_run_time}`);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/triggers" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
      "schedule": "0 9 * * *",
      "time_zone": "America/Argentina/Buenos_Aires",
      "display_name": "issue-solver",
      "interaction": {
          "agent": "antigravity-preview-05-2026",
          "input": [{"type": "text", "text": "Review open PRs in my-org/my-app for new comments and address feedback. Close issues whose PRs were merged. Then check for new issues labeled accepted, skip any already tracked in /workspace/solved-issues/, fix the rest, and open a PR for each. Save reports to /workspace/solved-issues/."}],
          "environment": {
              "type": "remote",
              "network": {
                  "allowlist": [
                      {
                          "domain": "api.github.com",
                          "transform": {
                              "Authorization": "Bearer ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                          }
                      },
                      {"domain": "github.com"}
                  ]
              }
          }
      }
  }'

درخواست CreateTrigger فیلدهای زیر را می‌پذیرد:

میدان نوع مورد نیاز توضیحات
schedule رشته بله عبارت کرون (مثلاً 0 * * * * برای هر ساعت، 0 9 * * 1-5 برای صبح‌های روزهای هفته).
time_zone رشته بله منطقه زمانی IANA (مثلاً UTC ، America/Argentina/Buenos_Aires ).
display_name رشته خیر نام قابل خواندن توسط انسان برای تریگر.
max_consecutive_failures عدد صحیح خیر حداکثر تعداد خطاها قبل از اینکه تریگر به طور خودکار متوقف شود. پیش‌فرض: ۵.
execution_timeout_seconds عدد صحیح خیر مدت زمان اجرا بر حسب ثانیه. پیش‌فرض: ۶۰۰.
interaction شیء بله یک CreateInteractionRequest که عامل، ورودی، ابزارها و محیط را تعریف می‌کند.

پاسخ شامل فیلدهای کلیدی زیر است:

میدان نوع توضیحات
id رشته شناسه منحصر به فرد برای تریگر. از این در تمام عملیات بعدی استفاده کنید.
status رشته وضعیت فعلی: active ، paused یا disabled .
next_run_time رشته مهر زمانی ISO 8601 برای اجرای برنامه‌ریزی‌شده‌ی بعدی.
consecutive_failure_count عدد صحیح تعداد اجراهای ناموفق متوالی از آخرین اجرای موفق.

محرک‌های فهرست

تمام محرک‌های مرتبط با پروژه خود را بازیابی کنید.

پایتون

triggers = client.triggers.list()
for trigger in triggers.triggers:
    print(f"{trigger.id}: {trigger.display_name} ({trigger.status})")

جاوا اسکریپت

const triggers = await client.triggers.list();
for (const trigger of triggers.triggers) {
    console.log(`${trigger.id}: ${trigger.display_name} (${trigger.status})`);
}

استراحت

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

یک ماشه بگیرید

پیکربندی کامل و وضعیت فعلی یک تریگر واحد را دریافت کنید.

پایتون

trigger = client.triggers.get(id="TRIGGER_ID")
print(f"Schedule: {trigger.schedule}")
print(f"Next run: {trigger.next_run_time}")

جاوا اسکریپت

const trigger = await client.triggers.get("TRIGGER_ID");
console.log(`Schedule: ${trigger.schedule}`);
console.log(`Next run: ${trigger.next_run_time}`);

استراحت

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

مکث و از سرگیری

شما می‌توانید یک تریگر را برای متوقف کردن اجراهای زمان‌بندی‌شده متوقف کنید و برای فعال‌سازی مجدد زمان‌بندی، آن را از سر بگیرید. متوقف کردن، اجراهای دستی را تحت تأثیر قرار نمی‌دهد.

پایتون

# Pause
client.triggers.update(id="TRIGGER_ID", status="paused")

# Resume
client.triggers.update(id="TRIGGER_ID", status="active")

جاوا اسکریپت

// Pause
await client.triggers.update("TRIGGER_ID", { status: "paused" });

// Resume
await client.triggers.update("TRIGGER_ID", { status: "active" });

استراحت

# Pause
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{"status": "paused"}'

# Resume
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{"status": "active"}'

حذف یک تریگر

یک تریگر را به طور دائم حذف کنید. تاریخچه اجرای قبلی حذف نمی‌شود.

پایتون

client.triggers.delete(id="TRIGGER_ID")

جاوا اسکریپت

await client.triggers.delete("TRIGGER_ID");

استراحت

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

فوراً یک تریگر اجرا کنید

فعال کردن یک تریگر بنا به درخواست بدون انتظار برای زمان برنامه‌ریزی شده بعدی. این قابلیت حتی اگر تریگر متوقف شده باشد نیز کار می‌کند.

پایتون

client.triggers.run(trigger_id="TRIGGER_ID")

جاوا اسکریپت

await client.triggers.run("TRIGGER_ID");

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/triggers/TRIGGER_ID/executions" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

فهرست اعدام‌ها

مشاهده تاریخچه اجرا برای یک تریگر. هر اجرا شامل یک status ، timestamps، یک interaction_id است که می‌توانید برای دریافت خروجی کامل تعامل از آن استفاده کنید، و یک environment_id که تأیید می‌کند همه اجراها در یک sandbox مشترک هستند.

پایتون

executions = client.triggers.list_executions(trigger_id="TRIGGER_ID")
for ex in executions.trigger_executions:
    print(f"{ex.id}: {ex.status} ({ex.start_time} - {ex.end_time})")

# Fetch the full interaction for an execution
interaction = client.interactions.get(id=ex.interaction_id)
print(interaction.output_text)

جاوا اسکریپت

const executions = await client.triggers.listExecutions("TRIGGER_ID");
for (const ex of executions.trigger_executions) {
    console.log(`${ex.id}: ${ex.status} (${ex.start_time} - ${ex.end_time})`);
}

// Fetch the full interaction for an execution
const interaction = await client.interactions.get(ex.interaction_id);
console.log(interaction.output_text);

استراحت

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

موجودی و قیمت‌گذاری

عامل ضد جاذبه (Antigravity agent) به صورت پیش‌نمایش از طریق Interactions API در Google AI Studio و Gemini API برای پروژه‌های رایگان و پولی در دسترس است.

قیمت‌گذاری از یک مدل پرداخت به ازای استفاده پیروی می‌کند که بر اساس توکن‌های مدل Gemini و ابزارهایی که عامل استفاده می‌کند، بنا شده است. برخلاف یک درخواست چت استاندارد که یک خروجی واحد تولید می‌کند، تعامل Antigravity یک گردش کار عامل‌محور است. یک درخواست واحد، یک حلقه مستقل از استدلال، اجرای ابزار، اجرای کد و مدیریت فایل را فعال می‌کند. پروژه‌های سطح رایگان شامل محدودیت نرخ رایگان و سهمیه استفاده هستند.

تعاملات ضد جاذبه، حلقه‌های خودکار چند نوبتی را اجرا می‌کنند و می‌توانند توکن‌های قابل توجهی مصرف کنند. برای محدود کردن استفاده از توکن ، کنترل‌های بودجه را روی درخواست خود تنظیم کنید. همچنین می‌توانید با جریان SSE ، پیشرفت را در زمان واقعی رصد کنید یا درخواست‌های در حال اجرا را لغو کنید.

کنترل‌های بودجه

max_total_tokens درون agent_config (با "type": "antigravity" ) تنظیم کنید تا تعداد کل توکن‌هایی (ورودی + خروجی + تفکر) که یک تعامل می‌تواند مصرف کند را محدود کند. توکن‌های ذخیره شده در حافظه پنهان (cached tokens) در این محدودیت محاسبه نمی‌شوند. وقتی عامل به این محدودیت می‌رسد، تعامل متوقف شده و با status: "incomplete" برمی‌گردد. محدودیت، بهترین تلاش است: میزان استفاده واقعی ممکن است بسته به زمانی که عامل بودجه را بین مراحل بررسی می‌کند، کمی بیشتر از آن باشد.

بودجه مربوط به درخواست تعامل را در agent_config در کنار agent و input تنظیم کنید.

پایتون

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyze the dataset in /workspace/data.csv and generate a summary report.",
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    },
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": "/workspace/data.csv",
                "content": "id,name,value\n1,alpha,100\n2,beta,200\n",
            }
        ],
    }
)
print(f"Status: {interaction.status}")  # "incomplete" if budget was hit
print(f"Tokens used: {interaction.usage.total_tokens}")

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Analyze the dataset in /workspace/data.csv and generate a summary report.",
    agent_config: {
        type: "antigravity",
        max_total_tokens: 50000
    },
    environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: "/workspace/data.csv",
                content: "id,name,value\n1,alpha,100\n2,beta,200\n",
            },
        ],
    },
});
console.log(`Status: ${interaction.status}`);
console.log(`Tokens used: ${interaction.usage.total_tokens}`);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Analyze the dataset in /workspace/data.csv and generate a summary report.",
    "agent_config": {
      "type": "antigravity",
      "max_total_tokens": 50000
    },
    "environment": {
      "type": "remote",
      "sources": [
        {
          "type": "inline",
          "target": "/workspace/data.csv",
          "content": "id,name,value\n1,alpha,100\n2,beta,200\n"
        }
      ]
    }
  }'

ادامه یک تعامل ناقص

وقتی یک تعامل status: "incomplete" را برمی‌گرداند، کار و زمینه عامل حفظ می‌شود. یک تعامل جدید با ارجاع به id تعامل اصلی و environment_id ارسال کنید تا از جایی که متوقف شده بود، ادامه یابد. تعامل جدید بودجه max_total_tokens خود را دریافت می‌کند.

پایتون

# Continue from where the agent stopped
continuation = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="continue",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    agent_config={
        "type": "antigravity",
        "max_total_tokens": 50000
    }
)
print(f"Status: {continuation.status}")

جاوا اسکریپت

const continuation = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "continue",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    agent_config: {
        type: "antigravity",
        max_total_tokens: 50000
    }
});
console.log(`Status: ${continuation.status}`);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "continue",
    "previous_interaction_id": "INTERACTION_ID",
    "environment": "ENVIRONMENT_ID",
    "agent_config": {
      "type": "antigravity",
      "max_total_tokens": 50000
    }
  }'

هزینه‌های تخمینی

هزینه‌ها بر اساس پیچیدگی وظیفه متفاوت است. عامل به طور خودکار تعداد فراخوانی‌های ابزار، اجرای کد و عملیات فایل مورد نیاز را تعیین می‌کند. تخمین‌های زیر بر اساس اجراها هستند.

دسته بندی وظایف توکن‌های ورودی توکن‌های خروجی هزینه معمول
تحقیق و ترکیب اطلاعات ۱۰۰ هزار تا ۵۰۰ هزار ۱۰ هزار تا ۴۰ هزار ۰.۳۰ تا ۱.۰۰ دلار
تولید سند و محتوا ۱۰۰ هزار تا ۵۰۰ هزار ۱۵ هزار تا ۵۰ هزار ۰.۳۰ تا ۱.۳۰ دلار
طراحی فرآیند و سیستم ۱۰۰ هزار تا ۴۰۰ هزار ۱۰ هزار تا ۳۰ هزار ۰.۲۵ تا ۰.۸۰ دلار
پردازش و تحلیل داده‌ها ۳۰۰ هزار تا ۳ میلیون ۳۰ هزار تا ۱۵۰ هزار ۰.۷۰ تا ۳.۲۵ دلار

۵۰ تا ۷۰ درصد از توکن‌های ورودی معمولاً ذخیره می‌شوند. گردش‌های کاری پیچیده با فراخوانی‌های ابزار زیاد می‌توانند ۳ تا ۵ میلیون توکن را در یک تعامل واحد جمع‌آوری کنند که هزینه‌ای تا حدود ۵ دلار دارد.

محاسبات محیطی (پردازنده، حافظه، اجرای سندباکس) در طول دوره پیش‌نمایش هزینه‌ای دریافت نمی‌کند .

محدودیت‌ها

  • وضعیت پیش‌نمایش: عامل ضد جاذبه و API تعاملات. ویژگی‌ها و طرحواره‌ها ممکن است تغییر کنند.
  • پیکربندی نسل پشتیبانی نشده: پارامترهای زیر پشتیبانی نمی‌شوند و خطای ۴۰۰ را برمی‌گردانند: temperature ، top_p ، top_k ، stop_sequences ، max_output_tokens .
  • خروجی ساختاریافته: عامل Antigravity از خروجی‌های ساختاریافته پشتیبانی نمی‌کند.
  • ابزارهای موجود نیستند: file_search ، computer_use و google_maps هنوز پشتیبانی نمی‌شوند.
  • محدودیت‌های MCP از راه دور: انتقال رویدادهای ارسالی از سرور (SSE) پشتیبانی نمی‌شود (از HTTP قابل پخش استفاده کنید). علاوه بر این، name سرور باید کاملاً با حروف کوچک و حروف الفبا باشد (استفاده از حروف بزرگ باعث ایجاد خطای عمومی 400 Bad Request می‌شود).
  • ابزار سیستم فایل: در حال حاضر هیچ ابزار سیستم فایلی وجود ندارد. این بخشی از environment است.
  • الزام ذخیره: اجرای عامل با استفاده از background=True نیاز به store=True دارد.
  • فراخوانی تابع فقط با وضعیت: فراخوانی تابع فقط در حالت با وضعیت پشتیبانی می‌شود. برای ادامه نوبت باید previous_interaction_id استفاده کنید؛ بازسازی دستی تاریخچه (حالت بدون وضعیت) پشتیبانی نمی‌شود.
  • انواع چندوجهی پشتیبانی نمی‌شوند. ورودی‌های صدا، ویدئو و سند در حال حاضر پشتیبانی نمی‌شوند. فقط متن و تصویر مجاز هستند.

قدم بعدی چیست؟