دليل البدء السريع لوكلاء Google المُدارين

يرشدك هذا الدليل إلى كيفية إنشاء "الوكلاء المُدارون" واستخدامهم على Gemini API، وذلك باستخدام وكيل Antigravity. ستُجري أول طلب إلى الوكيل، وتُكمل محادثة مترابطة، وتعرض الردّ تدريجيًا، وتنزِّل الملفات من وضع الحماية، وتعمل مع وكيل Antigravity المُدار.

إجراء أول تفاعل مع الوكيل

يؤدي طلب واحد إلى Interactions API إلى توفير مساحة اختبار على Linux، وتشغيل حلقة الوكيل، وعرض النتيجة. ستحدِّد ثلاث مَعلمات:

  • مرِّر agent على أنّه "antigravity-preview-05-2026", وهو الإصدار الحالي من الوكيل المُدار الذي حدّدناه مسبقًا والذي يمكن استخدامه لأغراض عامة.
  • حدِّد environment="remote" لتوفير بيئة مساحة اختبار جديدة.
  • أنشئ إدخالاً يحدِّد ما تريد أن يفعله الوكيل.

Python

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}")

JavaScript

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" \
-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. احفظ interaction.id وinteraction.environment_id لمواصلة المحادثة في مساحة الاختبار نفسها. استخدِم interaction.output_text للوصول إلى الردّ النهائي للوكيل. تسرد interaction.steps كل خطوة اتّخذها الوكيل (الاستنتاج، وطلبات الأدوات، وتطبيق الرموز البرمجية).

مواصلة المحادثة (محادثة مترابطة)

تتتبّع واجهة برمجة التطبيقات سمتَين مستقلّتَين للحالة:

  • سياق المحادثة: سجلّ المحادثات، وتتبُّع الاستنتاج، واستخدام الأدوات، باستخدام previous_interaction_id.
  • حالة البيئة: الملفات، والحِزم المثبَّتة، وحالة مساحة الاختبار، باستخدام environment.

مرِّر كلتا السمتَين في مكانهما المخصّص لاستئناف المحادثة:

Python

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)

JavaScript

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" \
-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" لاستخدام مساحة اختبار جديدة.

ضغط السياق التلقائي

في المحادثات المترابطة الطويلة، يمكن أن يزداد السجلّ الأوليّ لخطوات الاستدلال وطلبات الأدوات ومحتويات الملفات الكبيرة بسرعة ويستهلك مساحة كبيرة من السياق. لمنع أخطاء حدّ الرموز المميزة والحفاظ على تركيز الوكلاء المُدارين (منع "تدهور السياق")، تتضمّن Managed Agents API خطوة ضغط سياق أصلية عند حوالي 135 ألف رمز مميز. وتتم هذه العملية تلقائيًا.

عرض الردّ تدريجيًا

بالنسبة إلى المهام الطويلة، يمكنك عرض الردّ تدريجيًا لمشاهدة عمل الوكيل في الوقت الفعلي:

Python

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)

JavaScript

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

يعرض البث تدريجيًا كائنًا قابلاً للتكرار من اختلافات الخطوات، وهي نصوص إضافية ورموز الاستنتاج وتعديلات طلبات الأدوات. مزيد من المعلومات حول كيفية عرض الردود تدريجيًا في دليل البث تدريجيًا

تنزيل الملفات من البيئة

عندما ينشئ الوكيل ملفات داخل مساحة الاختبار. يمكنك تنزيلها باستخدام Files API من خلال طلب HTTP مباشر (ما مِن طريقة SDK حتى الآن):

Python

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")

JavaScript

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_agent: "antigravity-preview-05-2026" ويمكنك تمرير agent_config مع model الذي اخترته تمامًا كما تفعل في interactions.create. يمكنك أيضًا تحديد base_environment (إما من المصادر أو من خلال إنشاء نسخة من بيئة حالية). سيستخدم الوكيل هذه البيئة وإعدادات النموذج لكل تفاعل جديد.

من المصادر: حدِّد المصادر مضمّنة أو من مصادر أخرى، مثل GitHub أو Cloud Storage.

Python

agent = client.agents.create(
    id="fibonacci-analyst",
    base_agent="antigravity-preview-05-2026",
    agent_config={
        "type": "antigravity",
        "model": "gemini-3.6-flash",
    },
    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}")

JavaScript

const agent = await client.agents.create({
    id: "fibonacci-analyst",
    base_agent: "antigravity-preview-05-2026",
    agent_config: {
        type: "antigravity",
        model: "gemini-3.6-flash",
    },
    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" \
-d '{
    "id": "fibonacci-analyst",
    "base_agent": "antigravity-preview-05-2026",
    "agent_config": {
        "type": "antigravity",
        "model": "gemini-3.6-flash"
    },
    "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"
            }
        ]
    }
}'

استدعاء الوكيل المُدار

بعد حفظ وكيل مُدار، يمكنك استدعاؤه حسب رقم التعريف. في كل استدعاء، يتم إنشاء نسخة من البيئة الأساسية، لذا يبدأ كل تشغيل من جديد:

Python

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)

JavaScript

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

الخطوات التالية

  • وكيل Antigravity: الإمكانات والأدوات المتوافقة والإدخال المتعدّد الوسائط والتسعير والقيود
  • إنشاء وكلاء مُدارين: يمكنك توسيع نطاق وكيل Antigravity باستخدام التعليمات والمهارات والبيانات الخاصة بك.
  • البيئات: المصادر والشبكات ودورة الحياة وحدود الموارد
  • Interactions API: واجهة برمجة التطبيقات الأساسية للنماذج والوكلاء