بناء وكلاء مُدارين باستخدام Gemini API: دليل شامل للمطورين

كانت الوكلاء الذاتيون الذين يفكرون، ويكتبون وينفذون التعليمات البرمجية، ويتصفحون الويب، ويديرون الملفات يحتاجون سابقًا إلى أسابيع من العمل على البنية التحتية. مع إطلاق Managed Agents على Gemini API، اختزلت Google هذا الإعداد إلى استدعاء API واحد. استدعاء واحد ينشئ بيئة Linux آمنة ومؤقتة تستضيفها Google — ووكيلًا جاهزًا لإنجاز العمل الحقيقي داخلها.

يغطي هذا الدليل كل ما يحتاج المطورون إلى معرفته: كيف يعمل وكيل Antigravity، وكيفية بناء ونشر الوكلاء المخصصين، وكيفية تفريع البيئات لتشغيلات قابلة لإعادة الإنتاج، وكيفية تأمين الشبكات والاعتمادات، وكيف يتناسب Gemini CLI الجديد مع سير عمل يضع الوكلاء في المركز.

ما هي الوكلاء المُدارون في Gemini API؟

الوكلاء المُدارون هم لبنة تطويرية جديدة من Google لوكلاء الذكاء الاصطناعي الذاتيين على Gemini API. بدلًا من تجميع منطق التنسيق، وبيئات تنفيذ التعليمات البرمجية، وبنية استدعاء الأدوات، وعناصر التحكم الأمنية بنفسك، تتولى واجهة API كل ذلك.

استدعاء واحد إلى Interactions API يوفّر بيئة Linux معزولة، ويشغّل وكيلًا مدعومًا بـ Gemini، وينفذ مهمتك من البداية إلى النهاية. يمكن للوكيل التفكير والتخطيط، واستدعاء الأدوات، وتنفيذ التعليمات البرمجية، وإدارة الملفات، وتصفح الويب — وكل ذلك داخل بيئة تشغيل آمنة تديرها Google نيابةً عنك.

توفّر واجهتان هذا الإمكان:

• Interactions API — واجهة التشغيل. أرسل مهمة، واحصل على وكيل يفكر ويتصرف.
• Agents API — طبقة التحكم. عرّف وكلاء مسمّين وسجّلهم وأدرهم مع تعليمات وأدوات ومهارات وإعدادات بيئة مخصصة.

وكيل Antigravity: وكيل عام جاهز للاستخدام

أول وكيل مُدار عام الغرض على Gemini API هو Antigravity. وهو مدعوم بـ Gemini 3.5 Flash ويعمل على نفس الإطار الذي يقف خلف Antigravity IDE ومنتجات الوكلاء الأولى من Google. قبل Antigravity، كان Deep Research هو الوكيل المُدار الوحيد المتاح — وهو وكيل متخصص لسير عمل البحث متعدد الخطوات.

Antigravity هو النظير العام الغرض: استدعاء API واحد يوفّر بيئة Linux بعيدة ويبدأ العمل.

ما الذي يمكن لـ Antigravity فعله

داخل بيئته المعزولة المُدارة، يمكن لوكيل Antigravity أن:

• يفكر ويخطط باستخدام إطار وكيل Gemini
• ينفذ التعليمات البرمجية ويدير الملفات داخل بيئة Linux آمنة
• يتصفح الويب لجلب البيانات الحية ومعالجتها
• يستخدم أدوات تشمل البحث عبر الويب، وتنفيذ التعليمات البرمجية، وإدخال/إخراج الملفات

أول استدعاء API لـ Antigravity

إليك أبسط استدعاء ممكن لـ Antigravity — استدعاء API واحد يوفّر بيئة بعيدة، ويشغّل الوكيل، ويعيد الناتج:

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

هذا كل شيء. لا إعداد للحاويات. لا شيفرة لعزل البيئة. لا بنية scaffolding لاستدعاء الأدوات. Google تتولى كل ذلك.

البيئات الدائمة: وكلاء متعددو الجولات بحالة محفوظة

تستمر البيئات بين الاستدعاءات. الاستدعاء الأول يوفّر بيئة معزولة ويعيد environment_id. مرّر هذا المعرف في الطلبات اللاحقة، ويستأنف الوكيل العمل بكل الملفات والحزم والحالة تمامًا كما تركها الاستدعاء السابق.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

هذه الخاصية الحالةية هي ما يجعل سير العمل متعدد الخطوات عمليًا. يمكن لوكيل يثبت الحزم، ويكتب الملفات، ويجري التحليل في استدعاء واحد أن يسلّم كل ذلك بسلاسة إلى الاستدعاء التالي — من دون إعادة الإعداد، ولا إعادة التنزيل، ولا إعادة التنفيذ.

تقبل البيئات أيضًا بيانات خارجية عند بدء التشغيل: يمكن تحميل مستودعات Git، أو عناصر Google Cloud Storage، أو المحتوى المضمّن مباشرة إلى داخل البيئة المعزولة قبل أن يبدأ الوكيل العمل.

بناء وكلاء مُدارين مخصصين

يغطي وكيل Antigravity المهام العامة بشكل جيد. لكن حالات الاستخدام الإنتاجية تحتاج غالبًا إلى سلوك مخصص — تعليمات محددة، أو مهارات متخصصة، أو أدوات مملوكة، أو مصادر بيانات منتقاة. لهذا صُممت Agents API.

تتيح لك Gemini Managed Agents تجميع التعليمات، والمهارات، والأدوات، وبيئة العمل داخل وكيل مسمّى تستدعيه عبر المعرف. بدلًا من كتابة شيفرة تنسيق معقدة، يمكنك تعريف كل شيء بشكل تصريحي — في ملفات markdown مثل AGENTS.md وSKILL.md — ثم تسجيله مرة واحدة.

تعريف وكيل من المصادر

أنشئ وكيلًا من الصفر عبر تحديد تعليمات النظام والمصادر. يمكن أن تكون المصادر مستودعات GitHub، أو مسارات Google Cloud Storage، أو محتوى مضمّن. توفر المنصة بيئة معزولة جديدة مع ملفاتك عند كل استدعاء.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

بمجرد تسجيله، يصبح data-analyst وكيلًا دائمًا يمكنك استدعاؤه بالاسم. كل تشغيل يوفّر بيئة نظيفة بإعداداتك الدقيقة — من دون أي تسرب للحالة بين الاستدعاءات.

تفريع بيئة موجودة

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

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

بعد الحفظ، كل استدعاء لاحق لـ my-data-analyst يتفرع من تلك اللقطة الأساسية — ويبدأ من حالة نظيفة ومهيأة مسبقًا في كل مرة.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

نمط التفريع ثم التسجيل فعال بشكل خاص مع الوكلاء الذين يعتمدون على إعدادات ثقيلة: سلاسل تبعية معقدة، أو أصول نماذج كبيرة، أو قوالب مُجمّعة مسبقًا، والتي قد يستغرق إعادة بنائها وقتًا طويلًا في كل استدعاء.

الشبكات الآمنة ووكيل الاعتمادات

عادةً ما تحتاج الوكلاء الإنتاجيون إلى الوصول إلى خدمات خارجية — مثل GitHub، وواجهات API الداخلية، ومستودعات الحزم — وغالبًا ما يحتاجون إلى فعل ذلك من دون كشف الاعتمادات الحساسة داخل البيئة المعزولة. تتعامل Managed Agents مع الأمرين عبر egress proxy قابل للتكوين.

تخدم إعدادات الشبكة غرضين:

1. قوائم السماح تقيّد الاتصالات الصادرة بالنطاقات المسموح بها صراحةً، مما يمنع الوكيل من الوصول إلى خدمات خارجية غير مقصودة.
2. تحويلات الرؤوس تدرج الاعتمادات من جهة الخادم، بحيث لا تُمرَّر رموز API والأسرار إلى بيئة البيئة المعزولة نفسها.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

في هذا الإعداد، لا يمكن للوكيل الوصول إلا إلى api.github.com وpypi.org. أي محاولة للاتصال بنطاق آخر تُحظر. يتم تحويل طلبات GitHub تلقائيًا لتضمين ترويسة Authorization — ولا ترى شيفرة البيئة المعزولة الرمز مباشرةً أبدًا.

هذه البنية ضرورية للوكلاء الذين يعملون على مستودعات شيفرة داخلية، أو واجهات API مملوكة، أو أي بيئة تعد فيها نظافة الاعتمادات متطلبًا للامتثال.

Gemini API CLI: تجربة تطوير تضع الوكلاء في المركز

إلى جانب API، أطلقت Google أداة مفتوحة المصدر تجريبية Gemini API CLI صُممت لتتيح لوكلاء البرمجة التفاعل مع Gemini API بطريقة منظمة وصديقة للوكلاء.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

يعكس سير العمل agents init / agents test / agents create تحولًا في كيفية توقع Google من المطورين البناء على Gemini API: عرّف سلوك الوكيل في ملفات، اختبر محليًا، ثم انشره كوكيل مُدار مسمّى — وهي نفس الفكرة المألوفة في أدوات البنية التحتية ككود.

أدوات مكملة

إلى جانب CLI، تحافظ إضافتان على تحديث الوكلاء البرمجيين مع Gemini API:

• Gemini API Docs MCP server — يوفّر وصولًا حيًا إلى توثيق Gemini وSDKs ومعلومات النماذج عبر MCP. يمكن للوكلاء البرمجيين الاستعلام عن الوثائق مباشرة بدلًا من الاعتماد على بيانات تدريب قديمة.
• gemini-interactions-api Skill — يحقن أنماط وأفضل الممارسات الخاصة بـ Interactions API تلقائيًا في سياق الوكيل، بحيث يكتب الوكلاء المبنيون باستخدام Gemini Managed Agents شيفرة تفاعلية سليمة من البداية.

لماذا تهم الوكلاء المُدارون لحالات الاستخدام الإنتاجية

الرهان الأساسي وراء Managed Agents هو أن معظم العمل الشاق في تطوير الوكلاء لا يتعلق بالنموذج نفسه — بل بالبنية التحتية المحيطة به. العزل، وتكامل الأدوات، وإدارة الاعتمادات، وقابلية إعادة إنتاج البيئات، وأمن الشبكة كلها مشكلات يتعين على كل فريق يطلق وكلاء أن يحلها بشكل مستقل. تجعل Managed Agents هذه المشكلات مسؤولية Google بدلًا من ذلك.

هذا التحول له آثار عملية على النشر الإنتاجي:

تشغيلات قابلة لإعادة الإنتاج. تضمن البيئات المتفرعة أن كل استدعاء للوكيل يبدأ من أساس مماثل تمامًا — من دون انحراف في التبعيات، ولا تلوث للحالة بين التشغيلات.

سطح هجوم أقل. لا تدخل الاعتمادات إلى البيئة المعزولة أبدًا. وتكون حركة الخروج على الشبكة مقيدة بقوائم السماح. وبيئة التنفيذ مؤقتة ومعزولة. هذه ليست خطوات تشديد اختيارية؛ بل هي الإعداد الافتراضي.

تكرار أسرع. يعني سير العمل "التفريع ثم التسجيل" أن الفرق يمكنها التجربة بشكل تفاعلي، وتثبيت الإعداد، ثم ترقيته إلى وكيل مسمّى — من دون إعادة كتابة البنية التحتية بين النموذج الأولي والإنتاج.

توافق مع الأطر. تعمل Managed Agents مع أطر التنسيق التي تستخدمها الفرق بالفعل. وتشمل الشراكات عند الإطلاق Vercel AI SDK وLiteLLM وAgno وEigent وLlamaIndex — لذا لا تتطلب الاستفادة من البنية المُدارة إعادة كتابة كاملة لسير العمل الحالي.

الوكلاء المُدارون للمؤسسات

بالنسبة للمؤسسات التي تحتاج إلى تشغيل وكلاء مُدارين مخصصين على نطاق واسع، تقدم Google Gemini Enterprise Agent Platform — وهي نفس واجهات API، مع حوكمة إضافية، ورؤية مركزية، وعناصر تحكم على مستوى المؤسسة.

الوكلاء المُدارون في Gemini API متاحون حاليًا في مرحلة المعاينة. ويمكن لفرق المؤسسات الوصول إلى نفس لبنات الوكلاء المُدارة عبر Enterprise Agent Platform، مع عناصر تحكم إضافية للتدقيق، وفرض DLP، وحوكمة متعددة الفرق.

الخلاصة

يمنح إطلاق Gemini API Managed Agents المطورين ثلاثة أشياء كان من الصعب الحصول عليها معًا سابقًا: وكيلًا عامًا قويًا جاهزًا للاستخدام من البداية (Antigravity)، وواجهة API نظيفة لتعريف ونشر الوكلاء المخصصين بأمان إنتاجي، وتجربة تطوير — CLI، وMCP server، وSkills — مصممة لوكلاء يبنون وكلاء.

قرارات البنية التحتية سليمة: البيئات الدائمة، وتفريع البيئات، وقوائم السماح للخروج، وحقن الاعتمادات من جهة الخادم هي اللبنات الصحيحة لنشر الوكلاء في الإنتاج. تعكس CLI المفتوحة المصدر وSkill أيضًا إدراك Google أن تجربة المطور مع الوكلاء لا تقل أهمية عن قدرات النموذج نفسه.

بالنسبة للفرق التي تبني على منصة Eigent المحايدة للنماذج، تمثل Gemini Managed Agents وجهة نشر جذابة — وهي تتكامل جيدًا مع قدرة Eigent على توجيه المهام بذكاء عبر مزودي النماذج بينما تتولى Google طبقة التنفيذ المعزولة.

للبدء، جرّب وكيل Antigravity في AI Studio Playground، واقرأ توثيق Managed Agents، وثبّت Python SDK أو JavaScript SDK.

الأسئلة الشائعة

ما هي Gemini API Managed Agents؟

Gemini API Managed Agents هي وكلاء ذكاء اصطناعي ذاتيون يعملون داخل بيئات Linux معزولة ومستضافة لدى Google. استدعاء واحد إلى Interactions API يوفّر البيئة المعزولة، ويشغّل وكيلًا مدعومًا بـ Gemini، وينفذ مهمتك — بما في ذلك تنفيذ التعليمات البرمجية، وتصفح الويب، وإدارة الملفات — من دون أي إعداد للبنية التحتية من جانبك.

ما هو وكيل Antigravity؟

Antigravity هو وكيل Google العام المُدار على Gemini API، والمدعوم بـ Gemini 3.5 Flash. يمكنه التفكير والتخطيط، وتنفيذ التعليمات البرمجية، وإدارة الملفات، وتصفح الويب داخل بيئة Linux بعيدة وآمنة. ويستخدم نفس إطار الوكيل الذي يشغّل Antigravity IDE ومنتجات الوكلاء الأولى من Google.

كيف تعمل البيئات الدائمة؟

استدعاء التفاعل الأول مع environment="remote" يوفّر بيئة معزولة جديدة ويعيد environment_id. يؤدي تمرير هذا المعرف في الاستدعاءات اللاحقة إلى استئناف الوكيل في نفس البيئة — مع الحفاظ على جميع الملفات، والحزم المثبتة، والحالة. وهذا يتيح سير عمل متعدد الجولات بحالة محفوظة من دون إعادة الإعداد بين الاستدعاءات.

كيف أبني وكيلًا مُدارًا مخصصًا؟

استخدم Agents API لتعريف وكيل مسمّى عبر تحديد وكيل أساسي، وتعليمات، ومصادر (مستودعات GitHub، أو عناصر GCS، أو محتوى مضمّن). بمجرد تسجيله، استدعِ وكيلك بالاسم عبر Interactions API. أو يمكنك التكرار بشكل تفاعلي مع Antigravity، ثم تفريع البيئة الناتجة إلى وكيل مسمّى باستخدام client.agents.create() مع base_environment يشير إلى environment_id موجود.

كيف يعمل وكيل الاعتمادات؟

يقع egress proxy الخاص بالوكيل المُدار بين البيئة المعزولة والإنترنت. يمكنك تكوين allowlist للنطاقات المسموح بها، وباختيارك قواعد transform للرؤوس لكل نطاق. يقوم الوكيل بإدراج الرؤوس (مثل Authorization: Bearer <token>) في الطلبات الصادرة المطابقة تلقائيًا — لذلك لا تحصل شيفرة البيئة المعزولة أبدًا على وصول مباشر إلى قيم الرموز.

ما الأطر المتوافقة مع Gemini Managed Agents؟

تعمل Gemini Managed Agents مع Vercel AI SDK وLiteLLM وAgno وEigent وLlamaIndex مباشرة عند الإطلاق. وكون Interactions API قائمًا على REST يعني أن أي إطار تنسيق قادر على HTTP يمكنه دمجه.

ما هو Gemini API CLI؟

Gemini API CLI هي أداة مفتوحة المصدر تجريبية صُممت لتتيح للوكلاء البرمجيين التفاعل مع Gemini API. تدعم تشغيل المطالبات، وإنشاء الصور والصوت، وإدارة دورة حياة الوكيل المُدار كاملة — init وtest وcreate وrun — من سطر الأوامر.

هل Gemini Managed Agents متاحة للاستخدام المؤسسي؟

نعم. تتوفر نفس واجهات Gemini Managed Agents عبر Gemini Enterprise Agent Platform، مع عناصر تحكم إضافية في الحوكمة، ورؤية مركزية، وفرض DLP، وإدارة السياسات على مستوى المؤسسة. الوكلاء المُدارون في Gemini API متاحون حاليًا في مرحلة المعاينة.