تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إنشاء وكيل مُدار لتلخيص الأخبار التقنية باستخدام Gemini API

1. نظرة عامة

تتطوّر تكنولوجيات الذكاء الاصطناعي والتكنولوجيا بشكل أسرع من قدرة أي شخص على متابعتها. تتم إضافة نماذج وأوراق ومنتجات جديدة يوميًا. يمكن حلّ هذه المشكلة باستخدام وكيل ملخّص يجلب العناوين الرئيسية اليومية ويكتب ملخّصات موجزة وينشئ ملف PDF كل صباح، ولكن كان إنشاء هذا الوكيل يتطلّب اختيار إطار عمل وتحديد أدوات في Python وكتابة حلقة تنسيق وتعبئة حاوية ونشرها على Cloud Run. كل ذلك قبل أن يرسل الوكيل طلب ويب واحدًا.

تغيّر الوكلاء المُدارون في Gemini API المعادلة. يمكنك كتابة ملفَي إعداد بتنسيق Markdown ونص برمجي مُنشأ مسبقًا للعرض، وإجراء طلب واحد من واجهة برمجة التطبيقات، وسيتم تشغيل بيئة اختبارية حقيقية لنظام التشغيل Ubuntu، وتصفّح الويب، وكتابة الملخّصات، وإنشاء ملف PDF. ما مِن حاويات لا تتوفر عملية نشر. لا يوجد رمز تنسيق.

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

ما ستنشئه

إنشاء وتشغيل أول وكيل مُدار في بيئة اختبار حقيقية لنظام التشغيل Linux
تخصيص الوكيل باستخدام تعليمات مفصّلة
تنزيل ملف PDF الناتج من الوكيل
متابعة المحادثة لتحسين الملخّص بدون إعادة جلب المعلومات من الويب
حفظ إعدادات الوكيل واستدعاؤها باستخدام رقم التعريف في عمليات التشغيل المستقبلية

المتطلبات

‫Python 3.10 أو إصدار أحدث
مفتاح Gemini API مع تفعيل الفوترة: aistudio.google.com/api-keys
رصيد بقيمة دولار أمريكي واحد تقريبًا في واجهة برمجة التطبيقات (تتراوح تكلفة كل عملية تشغيل كاملة بين 0.30 و1.30 دولار أمريكي)

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

ثلاثة مستويات لأنظمة الذكاء الاصطناعي

قبل التوغّل في تفاصيل الرمز، إليك موضع "الوكلاء المُدارون" مقارنةً بالبديلَين الآخرَين:

المستوى	ما المقصود بذلك	مَن يدير البنية التحتية؟
النموذج اللغوي الكبير العادي	تكتب طلبًا، فيردّ عليك بنص. لا أملك يدَين أو ذاكرة أو اتصالاً بالإنترنت.	غير متوفّر: لا يمكنه تنفيذ أي إجراء بمفرده
الوكيل المستضاف ذاتيًا	يمكنك ربط حزمة تطوير التطبيقات (ADK) وLangChain وAutoGen وDocker والأدوات والذاكرة.	أنت: كل ذلك (أو منصة مُدارة مثل Agent Engine)
الوكيل المُدار	تحديد هدف توفّر Google وضع حماية آمنًا. يكتب الوكيل الرمز البرمجي ويشغّله ويقرأ الأخطاء ويبحث على الويب ويصلح الأخطاء تلقائيًا.	‫Google: كلّ ذلك

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

ما يمكنك إنشاؤه باستخدام ADK + Cloud Run

لإنشاء وكيل ملخّص أخبار يتصفّح الويب ويشغّل Python وينشئ ملف PDF، ستحتاج إلى كل ما يلي باستخدام ADK + Cloud Run:

# agent.py: define tools and wire up the agent
from google.adk.agents import LlmAgent
from google.adk.tools import google_search, built_in_code_execution

agent = LlmAgent(
    name="digest-agent",
    model=MODEL,
    instruction=AGENTS_MD,          # your editorial voice and rules
    tools=[google_search, built_in_code_execution],
)

# app.py: serve the agent over HTTP
from google.adk.runners import FastApiRunner
runner = FastApiRunner(agent=agent)
app = runner.app

# pdf_tool.py: custom tool, install reportlab, render PDF
# scraper.py: custom tool, fetch each news source
# streaming.py: wire agent events to your SSE endpoint

# Dockerfile: package everything
FROM python:3.12
COPY . /app
RUN pip install google-adk reportlab requests
CMD ["uvicorn", "app:app", "--host", "0.0.0.0"]

# Deploy to Cloud Run
gcloud run deploy digest-agent \
  --image gcr.io/your-project/digest-agent \
  --set-secrets GEMINI_API_KEY=gemini-key:latest \
  --memory 2Gi

ويكون ذلك قبل أن يتم تشغيل الوكيل مرة واحدة. سيظل بإمكانك التحكّم في عزل البيئة التجريبية (وبالتالي لا يمكن للوكيل إتلاف الخادم)، وتثبيت الحِزم، وإدارة الحالة بين استدعاءات الأدوات، وبنية البث الأساسية لإرسال الأحداث إلى العميل.

الخدمة التي تحلّ محلّ "وكلاء مُدارون"

from google import genai
client = genai.Client()

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="",
    stream=True,
    environment={
        "type": "remote",
        "sources": [          # your config files, mounted at startup
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

متطلبات استخدام "حزمة تطوير التطبيقات" + Cloud Run	المهام التي يتولّاها "الوكلاء المُدارون" نيابةً عنك
صورة الحاوية + الملف الشامل + التكامل المستمر/التسليم المستمر	بيئة اختبار Ubuntu مُدارة بالكامل (الإصدار 3.12 من Python والإصدار 22 من Node و4 وحدات معالجة مركزية وذاكرة وصول عشوائي بسعة 16 غيغابايت)
نشر Cloud Run وتوسيع نطاقه	يتم توفيرها لكل تفاعل، وتنتهي صلاحيتها تلقائيًا بعد 7 أيام من عدم النشاط
عزل وضع الحماية	معزولة لكل تفاعل
أداة PDF مخصّصة + `pip install`	يثبِّت الوكيل الحِزم داخل وضع الحماية
بنية بث SSE الأساسية	تعرض الدالة `stream=True` تكرارًا للأحداث
تعريفات الأدوات في Python	الأدوات المضمّنة: تصفُّح الويب، وتنفيذ الرموز البرمجية، ونظام الملفات
إدارة الحالة بين طلبات استخدام الأدوات	مضمّنة في حلقة الاستدلال الخاصة بالوكيل

يمكنك كتابة ملفات الإعداد (AGENTS.md وSKILL.md ونص برمجي مُعدّ مسبقًا) وإجراء طلب بيانات من واجهة برمجة التطبيقات. تتولّى Google جميع الإجراءات الأخرى.

طريقة عمل البيئة التجريبية

interactions.create() call
        │
        ▼
Google provisions Ubuntu sandbox (Python 3.12, Node 22, 4 CPU / 16 GB RAM)
        │
        ▼
Agent reasoning loop:
  plan → fetch URLs → run Python → write files → reason → repeat
        │
        ▼
Events stream back in real time: tool calls, text chunks, completion
        │
        ▼
interaction.completed → environment_id + interaction_id

تظل البيئة التجريبية متاحة لمدة 7 أيام من عدم النشاط. يمكنك استئنافها باستخدام environment_id لتحسين الناتج أو تنفيذ مهام متابعة أو إنشاء نسخة منها في وكيل محفوظ باسم.

3- إعداد

الخيار (أ): Cloud Shell (مقترَح)

انقر على الزر أدناه لفتح هذا الدرس العملي في Google Cloud Shell. يتم تثبيت جميع التبعيات مسبقًا.

الفتح في Cloud Shell

الخيار (ب): الإعداد المحلي

git clone https://github.com/Saoussen-CH/tech-digest-managed-agent.git
cd tech-digest-managed-agent

ثبِّت uv إذا لزم الأمر:

curl -LsSf https://astral.sh/uv/install.sh | sh

ضبط مفتاح واجهة برمجة التطبيقات

cp .env.example .env
cloudshell edit .env

اضبط المفتاح:

GEMINI_API_KEY=your-key-here

تثبيت الحِزم التابعة

uv sync

4. إجراء مكالمة الوكيل الأولى

فتح ملف البداية

cloudshell edit run_digest.py

يحتوي run_digest() على مهمة واحدة يجب إكمالها الآن وثلاث مهام أخرى للخطوة التالية. تمت تعبئة مساعدَين مسبقًا أعلاه:

يقرأ load_source(path) ملفًا من .agents/ بالنسبة إلى النص البرمجي. ستستخدمها في التمرين التالي لتثبيت الصوت التحريري وكتاب قواعد اللعب بتنسيق PDF وأداة العرض في البيئة التجريبية.
‫run_stream(stream): تعالج هذه الدالة سلسلة أحداث وتعرض (environment_id, interaction_id). لست بحاجة إلى كتابة حلقة معالجة الأحداث بنفسك.

ما يجب إضافته

مهمة 1: استبدِل pass بما يلي (تجاهَل المهمتَين 3 و4 في الوقت الحالي، فهما مخصّصتان للخطوة التالية):

    from google import genai
    client = genai.Client()

    stream = client.interactions.create(
        agent=BASE_AGENT,
        input="Fetch the Hacker News front page and list the top 5 stories.",
        stream=True,
        environment="remote",
    )

    environment_id, interaction_id = run_stream(stream)
    print(f"\nDone. environment_id={environment_id}")

وظيفة كل جزء

يقرأ genai.Client() قيمة GEMINI_API_KEY من البيئة. ويتم تنفيذ جميع الإجراءات الأخرى من خلال هذا العميل.

‫interactions.create() هي المكالمة الأساسية. تتوفّر أربع معلّمات تجعلها تعمل:

agent=BASE_AGENT: يختار وكيل Antigravity (antigravity-preview-05-2026)، وهو وكيل مُدار للأغراض العامة يستند إلى Gemini 3.5 Flash. تتضمّن هذه الأداة ثلاث أدوات مدمجة مفعَّلة تلقائيًا: code_execution (تشغيل Bash وPython وNode.js) وgoogle_search وurl_context (استرداد صفحات الويب وقراءتها). يتم تفعيل أدوات نظام الملفات (read_file وwrite_file وlist_files) تلقائيًا عند تمرير المَعلمة environment. يوفّر طلب واحد بيئة Ubuntu مُدارة بالكامل مع تثبيت Python 3.12 وNode.js 22 وgit وpip وcurl مسبقًا. لا حاجة إلى إنشاء حاوية أو نشرها لتشغيلها.
استبدِل input بالمهمة التي سيتم تنفيذها في هذا التشغيل. يتصفّح الوكيل Hacker News ويستدلّ على النتائج.
‫environment="remote": يوفّر وضع حماية جديدًا على السحابة الإلكترونية لهذا التفاعل.
‫stream=True: تعرض عنصرًا قابلاً للتكرار من الأحداث بدلاً من الحظر. بدون هذه السمة، تنتظر المكالمة من 30 إلى 90 ثانية وتعرض كل النتائج مرة واحدة على شكل interaction.output_text. باستخدام ميزة البث، يمكنك الاطّلاع على سبب ردّ الوكيل والتصرّف في الوقت الفعلي. لا يُعدّ البث ميزة متقدّمة هنا، بل هو الإعداد التلقائي الصحيح، لأنّ المربع الأسود الذي يظهر لمدة 90 ثانية لا يقدّم لك أي إشارة حول ما إذا كان البرنامج يعمل أو متوقفًا.

ما تم توفيره للتو: يؤدي كل طلب interactions.create() إلى تشغيل وضع حماية مخصّص:

المكوّن	المواصفات
نظام التشغيل	بيئة Ubuntu Linux معزولة
بيئات التشغيل المثبّتة مسبقًا	‫Python 3.12 وNode.js 22 وBash
الحوسبة	وحدة معالجة مركزية رباعية النواة، وذاكرة وصول عشوائي (RAM) بسعة 16 غيغابايت
إدارة السياق	يتم تفعيل ميزة "الضغط التلقائي" عند حوالي 135 ألف رمز مميز
الاتصال بالشبكات	الوصول إلى الويب خارجيًا من خلال Egress Proxy

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

‫environment_id هو معرّف لوضع الحماية الذي تم تنفيذه للتو. بعد interaction.completed، لا يتم إيقاف البيئة التجريبية، بل تبقى نشطة لمدة تصل إلى 7 أيام. يمكنك استخدام environment_id للرجوع إلى هذه الصفحة. مرِّرها إلى مكالمة interactions.create() ثانية وسيستأنف الوكيل العمل على نظام الملفات نفسه، مع الملفات والحِزم المثبَّتة نفسها، كما لو أنّه لم يتوقف أبدًا. تستخدم الخطوة التالية هذه السمة لتنزيل ملف PDF بدون إعادة تشغيل الوكيل، وتستخدمها الخطوة التي تليها لمواصلة المحادثة.

‫interaction_id هو معرّف لجولة المحادثة التي انتهت للتو. مرِّرها كـ previous_interaction_id في المكالمة التالية، وسيتذكّر الوكيل كل ما قاله وفعله في هذه الجولة.

تأكيد

uv run python run_digest.py

من المفترض أن تظهر لك النتائج المباشرة أثناء عمل الوكيل:

[agent started]
  [tool] run_code
Here are the top 5 stories currently on the Hacker News front page, retrieved via the official Hacker News API:

1. **Qwen 3.6 27B is the sweet spot for local development** — 471 points
2. **.self: A new top-level domain designed to support self-hosting** — 116 points
...
Done. environment_id=e3de58774073f75a6ef42924c6ce2e88

تعرض واجهة برمجة التطبيقات قيمة environment_id حقيقية حتى مع environment="remote". تم تشغيل وضع الحماية. ما ينقص هو الإعدادات: لا يوجد صوت ولا مهارة ولا أداة لإنشاء ملفات PDF. لقد طبع الوكيل القصص كنص وتوقّف. تضيف الخطوة التالية هذه الأذونات.

يتطابق كل سطر من الناتج مع حدث من run_stream():

`step.type`	التعريف	ما يمكن لـ "`run_stream()`" طباعته
`"url_context_call"`	وكيل يجلب عنوان URL	`[tool] url_context (https://...)`
`"code_execution_call"`	وكيل ينفّذ الرمز البرمجي في وضع الحماية	`[tool] run_code`
`"google_search_call"`	البحث على الويب	`[tool] google_search`
`"function_call"`	أدوات الملفات وغيرها	`[tool] read_file (/workspace/...)`
‫`step.delta` حيث `delta.type == "text"`	يكتب الوكيل نصًا	يتم بثّه مباشرةً إلى stdout

5- تخصيص الوكيل

لم يتضمّن الوكيل أي تعليمات: لا صوت ولا مهارة ولا أداة لإنشاء ملفات PDF. في هذه الخطوة، يتم تحميل ملفات الإعداد من .agents/ وتثبيتها في البيئة التجريبية.

ما الذي يجب تغييره؟

أجرِ أربعة تغييرات على run_digest.py:

TODO 2: أسفل load_source()، أضِف الثوابت الثلاثة على مستوى الوحدة (تكون هذه الثوابت خارج run_digest()، في أعلى الملف):

AGENTS_MD       = load_source(".agents/AGENTS.md")
SKILL_MD        = load_source(".agents/skills/digest-pdf/SKILL.md")
GENERATE_PDF_PY = load_source(".agents/skills/digest-pdf/scripts/generate_pdf.py")

افتح كل ملف لمعرفة ما يتم تحميله: AGENTS.md يضبط قواعد سير العمل والصوت التحريري، وSKILL.md هو دليل PDF خطوة بخطوة، وgenerate_pdf.py هو أداة العرض المسبقة الإنشاء التي سيشغّلها الوكيل.

لماذا AGENTS.md بدلاً من system_instruction؟ تقبل واجهة برمجة التطبيقات Interactions API أيضًا مَعلمة سلسلة system_instruction مباشرةً. يعمل كلا النهجين بشكل جيد، كما أنّهما يكمّلان بعضهما البعض عند استخدامهما معًا. AGENTS.md هو الخيار الأفضل هنا لأنّه يظهر بجانب الرمز في المستودع، ويتم التحكّم في إصداره مع بقية المشروع، ويكون دائمًا في سياق الوكيل من الرمز المميز الأول. استخدِم system_instruction لإجراء تعديلات سريعة على كل مكالمة، واستخدِم AGENTS.md لتعريفات الشخصيات الطويلة والإرشادات التي تريد إصدارها مع وكيلك.

الآن، أجرِ تغييرَين آخرَين داخل run_digest():

قائمة المهام 3: غيِّر environment من "remote" إلى قاموس المصادر، واضبط input على "":

        environment={
            "type": "remote",
            "sources": [
                {
                    "type": "inline",
                    "target": ".agents/AGENTS.md",
                    "content": AGENTS_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/SKILL.md",
                    "content": SKILL_MD,
                },
                {
                    "type": "inline",
                    "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                    "content": GENERATE_PDF_PY,
                },
            ],
        },

مطلوب اتّخاذ إجراء 4: أضِف الأسطر التالية بعد print(f"\nDone. environment_id={environment_id}") مباشرةً:

    set_key(".env", "ENVIRONMENT_ID", environment_id)
    set_key(".env", "INTERACTION_ID", interaction_id)

(تم استيراد set_key في أعلى run_digest.py.)

يؤدي ذلك إلى كتابة كلا المعرّفَين إلى .env أثناء هذا التشغيل، وبالتالي يمكن للخطوة التالية تنزيل ملف PDF بدون إعادة تشغيل الوكيل.

وظيفة كل مصدر

كل مصدر هو ملف يتم تحميله في نظام ملفات وضع الحماية عند بدء التشغيل قبل تشغيل الوكيل. تتطابق المسارات target مع الأماكن التي يتوقّع فيها تطبيق Antigravity العثور عليها:

.agents/
├── AGENTS.md                              ← auto-loaded as global instructions
└── skills/
    └── digest-pdf/
        ├── SKILL.md                       ← auto-discovered and registered as a skill
        └── scripts/
            └── generate_pdf.py            ← pre-built renderer the agent can run

`target` مسار	متغيّر	ماذا تفعل أداة الاختبار بالبيانات؟
`.agents/AGENTS.md`	`AGENTS_MD`	يتم تحميلها تلقائيًا كتعليمات ثابتة: أسلوب التحرير وسير العمل وقواعد التنفيذ
`.agents/skills/digest-pdf/SKILL.md`	`SKILL_MD`	يتم اكتشافها وتسجيلها تلقائيًا كمهارة محدّدة الاسم، ويستدعيها الوكيل بالاسم
`.agents/skills/digest-pdf/scripts/generate_pdf.py`	`GENERATE_PDF_PY`	عارض ملفات PDF مُنشأ مسبقًا، يكتب الوكيل `summaries.json` ثم يشغّل هذا النص البرمجي

المهارات هي معيار من عدّة منصات (agentskills.io). فهي تمنح الوكيل ذاكرة إجرائية، أي لا تقتصر على معرفة المعلومات، بل تشمل أيضًا كيفية تنفيذ مهمة معيّنة خطوة بخطوة. لا يتم تحميل نص SKILL.md إلا عندما يتم تشغيل المهارة، وتبقى البيانات الوصفية (الاسم والوصف) في السياق طوال الوقت. يُطلق على ذلك اسم "الإفصاح التدريجي"، وهو يحافظ على قدرة الاستيعاب نظيفة.

هناك أمران يجب ملاحظتهما هنا:

المهارة مقابل AGENTS.md: تكون AGENTS.md دائمًا في سياق الوكيل من الرمز المميز الأول: الصوت وقواعد سير العمل وقيود التنفيذ. SKILL.md يتم تحميلها عند الطلب فقط عندما يقرّر الوكيل أنّ المهارة مطلوبة لإنجاز المهمة. يجب أن يكون AGENTS.md موجزًا، ويُنصح بتضمين فهرس قصير في الأسفل يسرد المهارات المتاحة لكي يعرف الوكيل ما يبحث عنه. الجدول ## Skills في .agents/AGENTS.md هو بالضبط ما ذكرناه: فهو يخبر الوكيل أنّ digest-pdf متوفّر، وبالتالي يمكن أن تحمّل أداة الاختبار SKILL.md الكاملة عند الحاجة إليها في المهمة.
الوكلاء المُدارون مقابل حزمة نشر الوكلاء (ADK): تستخدم حزمة نشر الوكلاء المسار البرمجي: load_skill_from_dir("skills/digest-pdf") ثم SkillToolset(skills=[skill]) في رمز Python البرمجي. باستخدام "الوكلاء المُدارون"، يمكنك استخدام المسار المضمّن: يمكنك تحميل الملف من خلال environment.sources، وسيرصده نظام الاختبار من .agents/skills/*/SKILL.md تلقائيًا. ما مِن رمز تسجيل.

تأكيد

uv run python run_digest.py

تستغرق عملية التشغيل الآن من دقيقة إلى 3 دقائق. من المفترض أن ترى الوكيل يقرأ ملفات الإعدادات ويكتب الملخّصات ويحفظ ملف PDF:

[agent started]
  [tool] read_file (/.agents/skills/digest-pdf/SKILL.md)
  [tool] list_files (/.agents/skills/digest-pdf/scripts)
  [tool] read_file (/.agents/skills/digest-pdf/scripts/generate_pdf.py)
  [tool] run_code
  [tool] write_file (/workspace/summaries.json)
  [tool] run_code
  [tool] delete_file (/tmp/test_scrape.py)
I have successfully generated today's tech news digest and saved the formatted document to /workspace/digest.pdf.
Done. environment_id=4129ffd75574e308748e9425d7ec828f

أصبحت environment_id الآن قيمة حقيقية: تم تشغيل وضع الاختبار المعزول باستخدام ملفات الإعدادات وأنشأ الوكيل digest.pdf. في الخطوة التالية، يتم تنزيلها.

6. تنزيل ملف PDF

كتب الوكيل digest.pdf إلى /workspace/digest.pdf داخل البيئة التجريبية. تتوفّر لقطة البيئة كأرشيف tar من خلال Gemini Files API.

ثبِّت requests إذا لزم الأمر:

uv pip install requests

المعلومات المطلوب إدخالها

فتح "download_pdf.py" تتضمّن مهمتَين.

مطلوب اتّخاذ إجراء 1: ملء requests.get() المكالمة:

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

يمثّل عنوان URL لقطة البيئة التجريبية. تعرض الدالة params={"alt": "media"} وحدات بايت أولية بدلاً من البيانات الوصفية. يتم أيضًا إثبات ملكية GEMINI_API_KEY الحالي باستخدام Files API.

الخطوة 2: ابحث عن ملف PDF واستخرِجه من أرشيف tar:

            member = next(m for m in tar.getmembers() if m.name.endswith("workspace/digest.pdf"))
            tar.extract(member, path=tmp, filter="data")

يختلف بادئة مسار tar باختلاف عمليات التشغيل، لذا ابحث حسب اللاحقة بدلاً من الترميز الثابت للمسار الدقيق. يؤدي filter="data" إلى إيقاف تحذير الإيقاف النهائي في الإصدار 3.13 من Python بشأن استخراج ملفات tar غير الآمنة.

تأكيد

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

افتح digest.pdf في الدليل نفسه. يحتوي هذا الحقل على الملخّص المنسّق الذي أنشأه الوكيل من صفحات الويب المباشرة.

7. مواصلة المحادثة

لديك حاليًا اشتراك في digest.pdf. إذا كنت تريد الملف فقط، تكون قد انتهيت. تتعلق هذه الخطوة بشيء مختلف: الطلب من الوكيل تغيير الملخّص بدون إعادة جلب الويب.

لا يزال وضع الحماية نشطًا. لا يزال لدى الوكيل /workspace/digest.pdf ويتذكّر كل قصة لخصها. يؤدي إجراء مكالمة ثانية إلى interactions.create() إلى إرسال رسالة متابعة إلى بيئة الاختبار المعزولة نفسها. في هذا المثال، نطلب من التطبيق إضافة ملاحظة "أهمية الخبر" تحت كل قصة، ويعدّل التطبيق ملف PDF في مكانه، بدون إعادة جلب البيانات وبدون إعادة تلخيصها.

المعلومات المطلوب إدخالها

فتح "refine_digest.py" تتضمّن ثلاث مهام.

قائمتَا المهام 1 و2: املأ المَعلمتَين المتعدّدَتَي الأدوار داخل interactions.create():

    environment=environment_id,
    previous_interaction_id=interaction_id,

يستأنف environment=environment_id وضع الحماية نفسه مع ملفاته وحِزمه. يقدّم previous_interaction_id=interaction_id للوكيل سجلّ المحادثات. ولا يتغيّر أي شيء آخر عن المكالمة الأولى.

مهمة 3: الاحتفاظ بقيمة interaction_id الجديدة في .env بعد انتهاء حلقة معالجة الأحداث:

set_key(".env", "INTERACTION_ID", interaction_id)

يؤدي كل طلب interactions.create() إلى إنشاء interaction_id جديد. تعني إعادة كتابتها أنّ عملية التشغيل التالية ستمرر هذا التحسين كـ previous_interaction_id، وسيتم ربط عمليات التشغيل بشكل صحيح. لا يتغيّر معرّف وضع الحماية أبدًا، لذا لا يلزم تعديل ENVIRONMENT_ID.

المَعلمتان اللتان تجعلان المحادثة المترابطة تعملان

رقم التعريف	ما يحافظ عليه	التشبيه
`environment=environment_id`	الملفات والحِزم المثبَّتة وحالة النظام: كل شيء في نظام ملفات Linux	الحفاظ على مكتب العمل نفسه بين الاجتماعات
`previous_interaction_id=interaction_id`	سجلّ المحادثات: ما قاله الوكيل وما فعله في الجولات السابقة	تذكُّر ما تمت مناقشته في الاجتماع الأخير

يمكنك تمرير أيّ من المعرّفين بشكل مستقل:

‫environment_id فقط: إعادة استخدام الملفات والحِزم، ولكن بدء محادثة جديدة مفيدة لمهمة جديدة في مساحة العمل نفسها
previous_interaction_id فقط: مواصلة سياق المحادثة، ولكن في بيئة اختبار جديدة (ستتم إزالة الملفات).
كلاهما: استمرارية كاملة، وهو ما تستخدمه هذه الخطوة.

بدون environment_id: وضع حماية فارغ، بدون ملف PDF بدون previous_interaction_id: ما مِن سياق، ولا يمكن للوكيل تحسين قسم معيّن.

تأكيد

uv run python refine_digest.py

يجب أن يكون البث سريعًا، فالوكيل لا يعيد جلب أي بيانات. بعد الانتهاء من ذلك:

Refinement done.
Saved digest_v2.pdf (52,418 bytes)

افتح digest_v2.pdf وقارِنه بـ digest.pdf. يجب أن تتضمّن كل قصة الآن سطرًا بعنوان "أهمية هذه القصة".

8. الاحتفاظ بإعدادات الوكيل المُدار

لقد اجتازت كل مكالمة حتى الآن AGENTS.md وSKILL.md وgenerate_pdf.py المضمّنة. هذا الإجراء صالح، ولكن رمز الاتصال يحمل محتوى الملف الكامل في كل عملية تشغيل. agents.create() يدمج عملية الإعداد في وكيل محفوظ باسم على جهة Google. يتم في الاستدعاء التالي تمرير معرّف الوكيل فقط:

Inline calls:   send sources on every call
Named agent:    bake once → invoke by ID, no sources

المعلومات المطلوب إدخالها

فتح "save_agent.py" يتضمّن مهمة واحدة (المهمة 1).

لاحظ أنّه يتم استيراد الثوابت مباشرةً من run_digest.py (بدون تكرار):

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

مطلوب اتّخاذ إجراء 1: ملء agents.create() المكالمة:

agent = client.agents.create(
    id="my-digest",
    base_agent=BASE_AGENT,
    description="Daily tech digest with editorial voice and PDF generation.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": AGENTS_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/SKILL.md",
                "content": SKILL_MD,
            },
            {
                "type": "inline",
                "target": ".agents/skills/digest-pdf/scripts/generate_pdf.py",
                "content": GENERATE_PDF_PY,
            },
        ],
    },
)

base_environment (وليس environment) هو الفرق الأساسي عن الاتصال المضمّن في الخطوة السابقة: يتم تخزين المصادر من جهة Google ويتم تحميلها تلقائيًا في كل عملية استدعاء مستقبلية. يجب تشغيله مرة واحدة فقط، وليس في كل مرة يتم فيها تشغيل الملخّص.

التأكّد من صحة معلومات الوكيل: حفظ الوكيل

uv run python save_agent.py

Saved: my-digest
my-digest: Daily tech digest with editorial voice and PDF generation.

استدعاء الوكيل المحفوظ

فتح "invoke_agent.py" يتم استدعاء الوكيل المحفوظ حسب المعرّف بدون مصادر:

stream = client.interactions.create(
    agent="my-digest",
    input="",
    stream=True,
    environment="remote",
)

قارِن ذلك بالاستدعاء المضمّن: يتم استبدال agent=BASE_AGENT بـ "my-digest"، ويتم استبدال كتلة environment الكاملة التي تتضمّن ثلاثة مصادر مضمّنة بـ environment="remote". تمّت إضافة الإعدادات مسبقًا من جهة Google.

التحقّق: استدعاء الوكيل المحفوظ

uv run python invoke_agent.py

من المفترض أن يظهر لك البث المباشر نفسه الذي يظهر في عملية التنفيذ المضمّنة، ولكن لا يتضمّن طلب البحث أي ملفات مصدر. بعد اكتمال عملية التشغيل، يتم تعديل ENVIRONMENT_ID وINTERACTION_ID في .env لتتمكّن من مواصلة استخدام refine_digest.py كما كان من قبل.

[agent started]
  [tool] read_file
  [tool] write_file
  [tool] run_code
I have successfully created today's tech news digest.
Done. environment_id=9a1c3e02-...

9. تنظيف

تنتهي صلاحية وضع الحماية تلقائيًا بعد 7 أيام من عدم النشاط. لا توجد خوادم لإيقافها. لا تتوفر حاويات لحذفها.

إذا حفظت إعدادات وكيل، احذفها باتّباع الخطوات التالية:

uv run python delete_agent.py

10. ملخّص

لقد أنشأت وكيلًا مُدارًا من البداية، مفهومًا واحدًا في كل مرة. في ما يلي ما تعلّمه كل تمرين:

تمرين	المفهوم	Key API
إجراء مكالمتك الأولى	توفير بيئة اختبارية حقيقية لنظام التشغيل Linux وبث أحداثها مباشرةً	‫`interactions.create(agent, input, environment, stream=True)`، `event.event_type`
تخصيص الوكيل	تثبيت ملفات الإعداد والاحتفاظ بأرقام التعريف في `.env` في عملية التشغيل نفسها	‫`environment.sources`، `set_key`
تنزيل ملف PDF	تنزيل ملف PDF بدون إعادة تشغيل الوكيل	‫Gemini Files API `:download` في `download_pdf.py`
متابعة المحادثة	متابعة المحادثة بدون إعادة جلب الويب	‫`environment=environment_id`، `previous_interaction_id=interaction_id`
الاحتفاظ بإعدادات الوكيل	الاحتفاظ بإعدادات الوكيل واستدعاؤها حسب رقم التعريف بدون الحاجة إلى مصادر	‫`agents.create()`، `agents.list()`

الأنماط الرئيسية

مكالمة واحدة، وضع حماية واحد: تعالج interactions.create() جميع البنية الأساسية (لا حاجة إلى نشر الحاويات أو تثبيت الحِزم محليًا)
البث التقدّمي: stream=True يحوّل مربّعًا أسود مدته 90 ثانية إلى خلاصة مباشرة لاستدعاءات الأدوات وأجزاء النص
المصادر المضمّنة: يمكنك تحميل AGENTS.md وSKILL.md والنصوص البرمجية المُنشأة مسبقًا إلى وضع الحماية بدون أي خطوة تحميل أو نشر.
الاستفادة من ميزة "الاكتشاف التلقائي": يتم تلقائيًا اختيار الملفات الموضوعة في .agents/ (لا يلزم إعداد حزمة تطوير البرامج (SDK))
الحالة الثنائية الأبعاد: تتتبّع environment_id الملفات والحِزم، وتتتبّع previous_interaction_id سياق المحادثة، ويمكن تمرير أي منهما بشكل مستقل
تنزيل اللقطة: البيئة هي ملف tar كامل لنظام الملفات، ويمكن الوصول إليه من خلال Gemini Files API
الموظفون المحدّدون: يخبز agents.create() الإعداد بشكل دائم، ولا تمرر المكالمات المستقبلية سوى رقم تعريف الموظف وenvironment="remote"، بدون مصادر

‫ADK + Cloud Run في مقابل "الوكلاء المُدارون": نظرة سريعة على الفرق

إمكانية	‫ADK + Cloud Run	الوكلاء المُدارون في Gemini API
توفير وضع حماية	`docker build` + `gcloud run deploy`	`interactions.create()`
تحديد الأدوات	دوال Python المسجَّلة لدى الوكيل	الميزات المضمّنة: تصفّح الويب، وتنفيذ الرموز البرمجية، ونظام الملفات
تثبيت الحِزم	‫`pip install` في Dockerfile	يعمل الوكيل `pip install` داخل وضع الحماية
أحداث البث	بنية تحتية مخصّصة لخدمة SSE	`stream=True`
مواصلة جلسة	قاعدة بيانات الجلسات + إدخال السياق	`environment_id` + `previous_interaction_id`
ملفات الإعداد	مضمّن في الوكيل أو يتم إدخاله عند بدء التشغيل	تم التحميل عبر `environment.sources`
البنية الأساسية المطلوب إدارتها	الحاوية وCloud Run وخدمة إدارة الهوية وإمكانية الوصول والأسرار	بدون

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

مزيد من المعلومات حول الوكلاء المُدارون في مستندات Gemini API