شروع سریع نمایندگان مدیریت‌شده

این راهنما شما را در ایجاد و استفاده از Managed Agents در Gemini API با استفاده از Antigravity agent راهنمایی می‌کند. شما اولین تماس خود با Agent را برقرار می‌کنید، یک مکالمه چند مرحله‌ای را ادامه می‌دهید، پاسخ را پخش می‌کنید، فایل‌ها را از sandbox دانلود می‌کنید و با Antigravity agent کار می‌کنید.

اولین تعامل با کارشناس خود را اجرا کنید

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

  • agent را با عنوان "antigravity-preview-05-2026" وارد کنید، که نسخه فعلی عامل از پیش تعریف شده و همه منظوره مدیریت شده ماست.
  • برای ایجاد یک محیط سندباکس جدید و تازه، environment="remote" را تعریف کنید.
  • یک ورودی ایجاد کنید و مشخص کنید که می‌خواهید عامل چه کاری انجام دهد.

پایتون

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment="remote",
)

# Print the agent's final output
print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")

جاوا اسکریپت

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    input: "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents.",
    environment: "remote",
});

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

console.log(`Output: ${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" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "agent": "antigravity-preview-05-2026",
    "input": [{"type": "text", "text": "Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt. Then read the file and print its contents."}],
    "environment": {"type": "remote"}
}'

پاسخ یک شیء Interaction را برمی‌گرداند. برای ادامه مکالمه در همان sandbox interaction.id و interaction.environment_id را ذخیره کنید. برای دسترسی به پاسخ نهایی عامل interaction.output_text استفاده کنید. interaction.steps هر مرحله‌ای را که عامل انجام داده است (استدلال، فراخوانی ابزار، اجرای کد) فهرست می‌کند.

ادامه مکالمه (چند نوبتی)

این API دو بُعد مستقل از وضعیت را ردیابی می‌کند:

  • زمینه مکالمه: تاریخچه چت، ردیابی استدلال، استفاده از ابزار، استفاده از previous_interaction_id .
  • وضعیت محیط: فایل‌ها، بسته‌های نصب‌شده و وضعیت جعبه شنی، با استفاده از environment .

هر دو را در جای خودشان بگذارید تا مکالمه از سر گرفته شود:

پایتون

interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
)

print(interaction_2.output_text)

جاوا اسکریپت

const interaction2 = await client.interactions.create({
    agent: "antigravity-preview-05-2026",
    previous_interaction_id: interaction.id,
    environment: interaction.environment_id,
    input: "Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
}, { timeout: 300_000 });

console.log(interaction2.output_text);

استراحت

curl -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",
    "previous_interaction_id": "interaction_id_from_step_1",
    "environment": "environment_id_from_step_1",
    "input": [{"type": "text", "text": "Now plot the Fibonacci sequence as a line chart and save it as chart.png."}]
}'

فایل‌های نوبت ۱ ( fibonacci.txt ) در نوبت ۲ باقی می‌مانند. عامل همچنین متن مکالمه را حفظ می‌کند.

شما می‌توانید این حالت‌ها را به‌طور مستقل با هم ترکیب و مطابقت دهید:

  • پاک کردن مکالمه، نگه داشتن فایل‌ها: previous_interaction_id را حذف کنید، فقط شناسه محیط را با استفاده از environment برای یک مکالمه جدید در همان فضای کاری ارسال کنید.
  • ادامه مکالمه، فضای کاری جدید: برای یک فضای کاری جدید، مقدار previous_interaction_id را وارد کنید و environment="remote" را تنظیم کنید.

فشرده‌سازی خودکار متن

در مکالمات طولانی مدت و چند نوبتی، تاریخچه خام مراحل استدلال، فراخوانی ابزارها و محتوای فایل‌های بزرگ می‌تواند به سرعت رشد کرده و فضای متن قابل توجهی را اشغال کند. برای جلوگیری از خطاهای محدودیت توکن و حفظ تمرکز عامل (جلوگیری از "پوسیدگی متن")، عامل مدیریت شده یک مرحله فشرده‌سازی متن بومی با حدود ۱۳۵ هزار توکن ارائه می‌دهد. برای وقوع این اتفاق لازم نیست کاری انجام دهید.

پاسخ را پخش کنید

برای وظایف طولانی مدت، می‌توانید با تنظیم stream: true ، پاسخ را پخش کنید تا عملکرد عامل را به صورت بلادرنگ مشاهده کنید:

پایتون

from google import genai

client = genai.Client()

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

for event in stream:
    print(event)

جاوا اسکریپت

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

const client = new GoogleGenAI({});

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

for await (const event of stream) {
    console.log(event);
}

استراحت

curl -N -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": "Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    "environment": "remote",
    "stream": true
}'

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

دانلود فایل‌ها از محیط

عامل می‌تواند فایل‌هایی را درون sandbox ایجاد کند. برای دانلود آنها، می‌توانید از API فایل‌ها با یک درخواست HTTP مستقیم استفاده کنید:

پایتون

import os
import requests
import tarfile

env_id = interaction.environment_id
api_key = os.environ["GEMINI_API_KEY"]

response = requests.get(
    f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download",
    params={"alt": "media"},
    headers={"x-goog-api-key": api_key},
    allow_redirects=True,
)

with open("snapshot.tar", "wb") as f:
    f.write(response.content)

with tarfile.open("snapshot.tar") as tar:
    tar.extractall(path="extracted_snapshot")

جاوا اسکریپت

import fs from "fs";
import { execSync } from "child_process";

const envId = interaction.environment_id;
const apiKey = process.env.GEMINI_API_KEY || "";

const url = `https://generativelanguage.googleapis.com/v1beta/files/environment-${envId}:download?alt=media`;
const response = await fetch(url, {
    headers: {
        "x-goog-api-key": apiKey,
    },
});

if (!response.ok) {
    throw new Error(`Failed to download file: ${response.statusText}`);
}

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync("snapshot.tar", buffer);

if (!fs.existsSync("extracted_snapshot")) {
    fs.mkdirSync("extracted_snapshot");
}
execSync("tar -xf snapshot.tar -C extracted_snapshot");

console.log(fs.readdirSync("extracted_snapshot"));

استراحت

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

tar -xf snapshot.tar -C extracted_snapshot

ساخت یک عامل سفارشی

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

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

از منابع: می‌توانید منابع را به صورت درون‌خطی یا از منابع دیگری مانند GitHub یا Cloud Storage تعریف کنید. این مثال یک فایل AGENTS.md و یک دایرکتوری Skills از GitHub تعریف می‌کند:

پایتون

agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports.",
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }

        ],
    },
)

print(f"Created agent: {agent.id}")

جاوا اسکریپت

const agent = await client.agents.create({
    id: "fibonacci-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    base_environment: {
        type: "remote",
        sources: [
            {
                type: "inline",
                target: ".agents/AGENTS.md",
                content: "Always include a chart and a summary table in your reports.",
            },
            {
                type: "repository",
                source: "https://github.com/your-org/skills",
                target: ".agents/skills"
            }
        ],
    },
});

console.log(`Created agent: ${agent.id}`);

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a math analysis agent. Generate sequences, visualize them, and export results as PDF reports.",
    "base_environment": {
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always include a chart and a summary table in your reports."
            },
            {
                "type": "repository",
                "source": "https://github.com/your-org/skills",
                "target": ".agents/skills"
            }
        ]
    }
}'

از یک محیط موجود: از طریق تعاملات، روی یک محیط تکرار کنید و سپس آن را به عنوان پایه برای عامل خود که به شناسه آن ارجاع می‌دهد، تنظیم کنید:

پایتون

agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-05-2026",
    system_instruction="You are a math analysis agent.",
    base_environment=interaction.environment_id,
)

جاوا اسکریپت

const agent = await client.agents.create({
    id: "fibonacci-analyst",
    base_agent: "antigravity-preview-05-2026",
    system_instruction: "You are a math analysis agent.",
    base_environment: interaction.environment_id,
});

استراحت

curl -X POST "https://generativelanguage.googleapis.com/v1beta/agents" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Api-Revision: 2026-05-20" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a math analysis agent.",
    "base_environment": "environment_id_from_previous_interaction"
}'

عامل به طور خودکار فایل .agents/AGENTS.md را به عنوان دستورالعمل‌های سیستمی و هر فایل SKILL.md را در مسیر .agents/skills/ به عنوان قابلیت بارگذاری می‌کند. برای مشاهده قالب کامل تعریف عامل، مهارت‌ها و پیکربندی پیشرفته، به بخش «ساخت عامل‌های سفارشی» مراجعه کنید.

عامل سفارشی را فراخوانی کنید

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

پایتون

result = client.interactions.create(
    agent="fibonacci-analyst",
    input="Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment="remote",
)

print(result.output_text)

جاوا اسکریپت

const result = await client.interactions.create({
    agent: "fibonacci-analyst",
    input: "Generate the first 50 prime numbers, plot their distribution, and save a PDF report.",
    environment: "remote",
}, {
    timeout: 300_000,
});

console.log(result.output_text);

استراحت

curl -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": "fibonacci-analyst",
    "environment": "remote",
    "input": "Generate the first 50 prime numbers, plot their distribution, and save a PDF report."
}'

این از شاخه‌های system_instruction ، tools و environment که قبلاً از base_environment تعریف شده‌اند، استفاده می‌کند. همچنین همه چیز می‌تواند در هر تعامل بازنویسی شود.

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