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

این راهنما شما را در ایجاد و استفاده از 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" را تنظیم کنید.

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

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

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

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

پایتون

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 دانلود کنید (هنوز از روش SDK استفاده نشده است):

پایتون

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

ذخیره یک عامل مدیریت‌شده

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

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

از منابع: منابع را به صورت درون خطی یا از منابع دیگری مانند GitHub یا Cloud Storage تعریف کنید.

پایتون

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"Saved 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(`Saved 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"
            }
        ]
    }
}'

عامل مدیریت‌شده را فراخوانی کنید

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

پایتون

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."
}'

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

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