با استفاده از Gemini API، یک عامل مدیریت‌شده‌ی خلاصه‌ی فناوری بسازید

۱. مرور کلی

چشم‌انداز هوش مصنوعی و فناوری سریع‌تر از آن چیزی که هر کسی بتواند ردیابی کند، حرکت می‌کند. مدل‌ها، مقالات و محصولات جدید روزانه منتشر می‌شوند. یک عامل خلاصه‌کننده که عناوین امروز را دریافت می‌کند، خلاصه‌های دقیقی می‌نویسد و هر روز صبح یک فایل PDF تولید می‌کند، این مشکل را حل می‌کند، اما ساختن چنین عاملی قبلاً به معنای انتخاب یک چارچوب، تعریف ابزارها در پایتون، نوشتن یک حلقه تنظیم، بسته‌بندی یک کانتینر و استقرار در Cloud Run بود. همه این‌ها قبل از آن بود که عامل یک درخواست وب واحد ارسال کند.

عامل‌های مدیریت‌شده در رابط برنامه‌نویسی کاربردی Gemini معادله را تغییر می‌دهند. شما دو فایل پیکربندی markdown و یک اسکریپت رندر از پیش ساخته شده می‌نویسید، یک فراخوانی API انجام می‌دهید و یک سندباکس واقعی اوبونتو بوت می‌شود، وب را مرور می‌کند، خلاصه‌های شما را می‌نویسد و یک PDF تولید می‌کند. بدون کانتینر. بدون استقرار. بدون کد تنظیم.

در این آزمایشگاه کد، شما دقیقاً همان عامل را خواهید ساخت: از یک تابع خالی تا یک خلاصه روزانه‌ی کاری، هر بار یک مفهوم.

آنچه خواهید ساخت

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

آنچه نیاز دارید

  • پایتون ۳.۱۰+
  • یک کلید API جمینی با قابلیت پرداخت: aistudio.google.com/api-keys
  • حدود ۱ دلار اعتبار API (هزینه هر دوره کامل ۰.۳۰ تا ۱.۳۰ دلار است)

۲. منظور از نمایندگان مدیریت‌شده در رابط برنامه‌نویسی نرم‌افزار Gemini چیست؟

سه سطح از سیستم‌های هوش مصنوعی

قبل از پرداختن به کد، در اینجا به بررسی جایگاه Managed Agents نسبت به دو گزینه دیگر می‌پردازیم:

سطح

آنچه هست

چه کسی زیرساخت‌ها را مدیریت می‌کند؟

استاندارد LLM

شما دستور می‌دهید، با متن پاسخ می‌دهد. نه دستی، نه حافظه‌ای، نه اینترنتی.

ناموجود: به تنهایی نمی‌تواند کاری انجام دهد

نماینده خود میزبان

شما ADK/LangChain/AutoGen + Docker + tools + memory را سیم‌کشی می‌کنید.

شما: همه آن (یا یک پلتفرم مدیریت‌شده مانند Agent Engine)

عامل مدیریت‌شده

شما به آن هدف می‌دهید. گوگل یک محیط امن (sandbox) فراهم می‌کند. عامل کد را می‌نویسد، آن را اجرا می‌کند، خطاها را می‌خواند، وب را جستجو می‌کند و اشکالات را به صورت خودکار برطرف می‌کند.

گوگل: همه چیز

این آزمایشگاه کد مربوط به ردیف سوم است. شما یک وظیفه و فایل‌های پیکربندی را ارائه می‌دهید. گوگل بقیه موارد را مدیریت می‌کند.

آنچه با ADK + Cloud Run خواهید ساخت

برای ساخت یک عامل خلاصه اخبار که وب را مرور می‌کند، پایتون را اجرا می‌کند و 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

این قبل از آن است که عامل یک بار اجرا شود. شما هنوز هم ایزوله‌سازی سندباکس (بنابراین عامل نمی‌تواند به سرور شما آسیب برساند)، نصب بسته، مدیریت وضعیت بین فراخوانی‌های ابزار و زیرساخت استریمینگ برای ارسال رویدادها به کلاینت را در اختیار دارید.

چه چیزی جایگزین Managed Agents می‌شود؟ 

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,
            },
        ],
    },
)

آنچه ADK + Cloud Run نیاز دارد

آنچه نمایندگان مدیریت‌شده برای شما انجام می‌دهند

تصویر کانتینر + داکرفایل + CI/CD

سندباکس اوبونتو کاملاً مدیریت‌شده (پایتون ۳.۱۲، نود ۲۲، ۴ پردازنده / ۱۶ گیگابایت رم)

استقرار + مقیاس‌بندی Cloud Run

به ازای هر تعامل ارائه می‌شود، پس از ۷ روز عدم فعالیت به طور خودکار منقضی می‌شود

جداسازی در جعبه شنی

ایزوله به ازای هر تعامل

ابزار PDF سفارشی + pip install

عامل بسته‌ها را درون جعبه شنی نصب می‌کند

زیرساخت استریمینگ SSE

stream=True یک رویداد قابل تکرار را برمی‌گرداند

تعریف ابزار در پایتون

ابزارهای داخلی: مرور وب، اجرای کد، سیستم فایل

مدیریت وضعیت بین فراخوانی‌های ابزار

در حلقه استدلال عامل تعبیه شده است

شما فایل‌های پیکربندی ( AGENTS.md ، SKILL.md ، یک اسکریپت از پیش ساخته شده) را می‌نویسید و یک فراخوانی API انجام می‌دهید. گوگل بقیه کارها را انجام می‌دهد.

نحوه کار جعبه شنی 

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

سندباکس به مدت ۷ روز عدم فعالیت ادامه می‌یابد. می‌توانید آن را با environment_id از سر بگیرید تا خروجی را اصلاح کنید، وظایف بعدی را اجرا کنید یا آن را در یک عامل نامگذاری شده ذخیره شده فورک کنید.

۳. راه‌اندازی

برای باز کردن این آزمایشگاه کد در پوسته ابری گوگل، روی دکمه زیر کلیک کنید. همه وابستگی‌ها از قبل نصب شده‌اند.

باز کردن در 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

کلید API خود را پیکربندی کنید 

cp .env.example .env
cloudshell edit .env

کلید خود را تنظیم کنید: 

GEMINI_API_KEY=your-key-here

نصب وابستگی‌ها 

uv sync

۴. اولین تماس خود را با کارشناس مربوطه برقرار کنید

فایل آغازگر را باز کنید 

cloudshell edit run_digest.py

run_digest() یک TODO برای پر کردن در حال حاضر و سه TODO دیگر برای مرحله بعدی دارد. دو کمکی از قبل در بالای آن پر شده‌اند:

  • load_source(path) : فایلی را از .agents/ نسبت به اسکریپت می‌خواند. در تمرین بعدی از آن برای سوار کردن صدای ویراستار، فایل PDF playbook و رندرکننده در sandbox استفاده خواهید کرد.
  • run_stream(stream) : جریان رویداد را پردازش می‌کند و (environment_id, interaction_id) را برمی‌گرداند. نیازی نیست خودتان حلقه رویداد را بنویسید.

چه چیزی اضافه کنیم

TODO 1: به جای pass بنویسید (TODO های 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 به طور خودکار فعال می‌شوند. با یک فراخوانی، یک محیط اوبونتو کاملاً مدیریت‌شده با Python 3.12، Node.js 22، git، pip و curl از پیش نصب‌شده فراهم می‌شود. هیچ کانتینری برای ساخت و هیچ استقراری برای اجرا وجود ندارد.
  • input : وظیفه مربوط به این اجرا. عامل، اخبار هکرها را مرور می‌کند و در مورد نتایج استدلال می‌کند.
  • environment="remote" : یک فضای ابری جدید برای این تعامل فراهم می‌کند.
  • stream=True : به جای مسدود کردن، مجموعه‌ای از رویدادها را برمی‌گرداند. بدون آن، فراخوانی 30 تا 90 ثانیه منتظر می‌ماند و تمام خروجی‌ها را به صورت interaction.output_text برمی‌گرداند. با پخش جریانی، دلیل عامل را می‌بینید و همانطور که اتفاق می‌افتد عمل می‌کنید. پخش جریانی در اینجا یک ویژگی پیشرفته نیست: پیش‌فرض درست است، زیرا یک جعبه سیاه 90 ثانیه‌ای هیچ سیگنالی در مورد اینکه آیا عامل کار می‌کند یا گیر کرده است، به شما نمی‌دهد.

چیزی که شما فراهم کردید: هر interactions.create() یک جعبه شنی اختصاصی را بوت می‌کند:

کامپوننت

مشخصات

سیستم عامل

محیط ایزوله لینوکس اوبونتو

زمان‌های اجرای از پیش نصب شده

پایتون ۳.۱۲، نود جی‌اس ۲۲، بش

محاسبه

پردازنده ۴ هسته‌ای، رم ۱۶ گیگابایتی

مدیریت زمینه

فشرده‌سازی خودکار در حدود ۱۳۵ هزار توکن فعال می‌شود

شبکه‌سازی

دسترسی به وب خروجی از طریق پروکسی Egress

عامل می‌تواند هر بسته‌ای را با pip یا npm نصب کند، فایل‌ها را بخواند و بنویسد و درخواست‌های وب خروجی ارسال کند. دستگاه و اعتبارنامه‌های شما هرگز دست‌کاری نمی‌شوند.

environment_id یک هندل برای sandbox است که تازه اجرا شده است. پس از interaction.completed ، sandbox خاموش نمی‌شود: تا ۷ روز زنده می‌ماند. environment_id روشی است که شما به آن برمی‌گردید. آن را به یک interactions.create() دوم منتقل کنید و agent در همان سیستم فایل، با همان فایل‌ها و بسته‌های نصب شده، کار خود را از سر می‌گیرد، گویی هرگز آنجا را ترک نکرده است. مرحله بعدی از آن برای دانلود PDF بدون اجرای مجدد agent استفاده می‌کند و مرحله بعد از آن از آن برای ادامه مکالمه استفاده می‌کند.

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

API حتی با environment="remote" یک environment_id واقعی برمی‌گرداند. سندباکس اجرا شد. چیزی که کم است پیکربندی است: بدون صدا، بدون مهارت، بدون مولد 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) منتقل می‌شود

۵. شخصی‌سازی عامل

عامل هیچ دستورالعملی نداشت: نه صدایی، نه مهارتی، نه تولیدکننده‌ی PDF. در این مرحله، فایل‌های پیکربندی را از .agents/ بارگذاری می‌کنید و آنها را در sandbox قرار می‌دهید.

چه چیزی را تغییر دهیم

چهار تغییر در run_digest.py ایجاد کنید:

مرحله ۲: در زیر 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 رندرکننده از پیش ساخته شده‌ای است که عامل اجرا خواهد کرد.

حالا دو تغییر دیگر در run_digest() ایجاد کنید:

کار ۳: environment از "remote" به sources dict تغییر دهید و 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,
                },
            ],
        },

مرحله ۴: این خطوط را درست بعد از 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 را دانلود کرد.

کاری که هر منبع انجام می‌دهد

هر منبع، فایلی است که در هنگام راه‌اندازی و قبل از اجرای عامل، در سیستم فایل sandbox نصب می‌شود. مسیرهای target با جایی که Antigravity harness انتظار دارد آنها را پیدا کند، مطابقت دارند: 

.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 را می‌نویسد و سپس این اسکریپت را اجرا می‌کند.

تأیید 

uv run python run_digest.py

حالا اجرا ۱ تا ۳ دقیقه طول می‌کشد. باید ببینید که عامل فایل‌های پیکربندی را می‌خواند، خلاصه‌ها را می‌نویسد و 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 اکنون یک مقدار واقعی است: sandbox با فایل‌های پیکربندی شما اجرا شد و عامل digest.pdf را ایجاد کرد. مرحله بعدی آن را دانلود می‌کند.

۶. فایل PDF را دانلود کنید

عامل digest.pdf در /workspace/digest.pdf درون سندباکس نوشت. اسنپ‌شات محیط به صورت یک آرشیو tar از طریق رابط برنامه‌نویسی Gemini Files در دسترس است.

requests نصب در صورت نیاز: 

uv pip install requests

چه چیزی را پر کنیم

download_pdf.py باز کنید. این فایل دو TODO دارد.

کار ۱: فراخوانی 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 به snapshot مربوط به sandbox اشاره می‌کند. params={"alt": "media"} به جای فراداده، بایت‌های خام را برمی‌گرداند. GEMINI_API_KEY موجود شما، API فایل‌ها را نیز احراز هویت می‌کند.

مرحله ۲: پیدا کردن و استخراج فایل 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" هشدار منسوخ شدن پایتون ۳.۱۳ در مورد استخراج ناامن tar را سرکوب می‌کند.

تأیید 

uv run python download_pdf.py

Saved digest.pdf (48,231 bytes)

digest.pdf در همان دایرکتوری باز کنید. این فایل شامل فایل خلاصه فرمت‌شده‌ای است که عامل از صفحات وب زنده تولید کرده است.

۷. مکالمه را ادامه دهید

شما از قبل digest.pdf دارید. اگر فقط فایل را می‌خواستید، کار تمام است. این مرحله در مورد چیز متفاوتی است: درخواست از عامل برای تغییر digest بدون واکشی مجدد وب.

سندباکس هنوز فعال است. عامل هنوز /workspace/digest.pdf را دارد و هر داستانی را که خلاصه کرده به خاطر می‌آورد. فراخوانی دوم interactions.create() یک پیام پیگیری به همان سندباکس ارسال می‌کند. در اینجا از آن می‌خواهید که یک یادداشت «چرا مهم است» زیر هر داستان اضافه کند و PDF را بدون واکشی مجدد و خلاصه‌سازی مجدد، به‌روزرسانی می‌کند.

چه چیزی را پر کنیم

refine_digest.py را باز کنید. این فایل سه TODO دارد.

TODO های ۱ و ۲: دو پارامتر multi-turn را درون interactions.create() وارد کنید: 

    environment=environment_id,
    previous_interaction_id=interaction_id,

environment=environment_id همان sandbox را با فایل‌ها و بسته‌هایش از سر می‌گیرد. previous_interaction_id=interaction_id تاریخچه مکالمات عامل را به او می‌دهد. از اولین فراخوانی هیچ چیز دیگری تغییر نمی‌کند.

مرحله ۳: مقدار interaction_id جدید را پس از حلقه رویداد، در فایل .env ذخیره کنید: 

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

هر فراخوانی interactions.create() یک interaction_id جدید تولید می‌کند. نوشتن مجدد آن به این معنی است که اجرای بعدی این اصلاح را به عنوان previous_interaction_id پشت سر می‌گذارد و زنجیره‌سازی به درستی انجام می‌شود. شناسه sandbox هرگز تغییر نمی‌کند، بنابراین ENVIRONMENT_ID نیازی به به‌روزرسانی ندارد.

دو پارامتری که باعث می‌شوند چند دور زدن کار کند

شناسه

آنچه را که حفظ می‌کند

مقایسه

environment=environment_id

فایل‌ها، بسته‌های نصب‌شده، وضعیت سیستم: همه چیز در سیستم فایل لینوکس

نگه داشتن میز اداری یکسان بین جلسات

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 مقایسه کنید. اکنون باید به هر داستان یک خط «چرا مهم است» اضافه شده باشد.

۸. پیکربندی عامل مدیریت‌شده را حفظ کنید

هر فراخوانی تاکنون به صورت درون‌خطی به AGENTS.md ، SKILL.md و generate_pdf.py ارسال شده است. این روش جواب می‌دهد، اما کد فراخوانی شما در هر اجرا، محتوای کامل فایل را حمل می‌کند. agents.create() پیکربندی را در یک عامل ذخیره‌شده با نام در سمت گوگل ذخیره می‌کند. فراخوانی بعدی فقط شناسه عامل را ارسال می‌کند: 

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

چه چیزی را پر کنیم

save_agent.py را باز کنید. این یک TODO (TODO 1) دارد.

توجه داشته باشید که ثابت‌ها مستقیماً از run_digest.py وارد شده‌اند (بدون تکرار): 

from run_digest import BASE_AGENT, AGENTS_MD, SKILL_MD, GENERATE_PDF_PY

مرحله ۱: فراخوانی 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 ) تفاوت کلیدی با فراخوانی درون‌خطی در مرحله قبل است: منابع در سمت گوگل ذخیره می‌شوند و در هر فراخوانی بعدی به طور خودکار نصب می‌شوند. آن را یک بار اجرا کنید، نه در هر اجرای خلاصه.

تأیید کنید: عامل را ذخیره کنید 

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" جایگزین شده است. پیکربندی از قبل در سمت گوگل اعمال شده است.

تأیید: عامل ذخیره شده را فراخوانی کنید 

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-...

۹. تمیز کردن

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

اگر پیکربندی عامل را ذخیره کرده‌اید، آن را حذف کنید: 

uv run python delete_agent.py

۱۰. خلاصه

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

ورزش

مفهوم

API کلید

اولین تماس خود را برقرار کنید

یک سندباکس واقعی لینوکس تهیه کنید و رویدادهای آن را به صورت زنده پخش کنید

interactions.create(agent, input, environment, stream=True) , event.event_type

سفارشی‌سازی عامل

فایل‌های پیکربندی را mount کنید؛ شناسه‌ها را در همان اجرا در .env ‎ حفظ کنید

environment.sources ، set_key

دانلود پی دی اف

دانلود فایل PDF بدون اجرای مجدد عامل

API فایل‌های Gemini :download در download_pdf.py

ادامه گفتگو

ادامه مکالمه بدون نیاز به باز کردن مجدد وب

environment=environment_id ، previous_interaction_id=interaction_id

پیکربندی عامل Persist

پیکربندی عامل را حفظ کنید؛ با شناسه فراخوانی کنید، هیچ منبعی لازم نیست

agents.create() ، agents.list()

الگوهای کلیدی

  1. یک فراخوانی، یک جعبه شنی : interactions.create() تمام زیرساخت‌ها را مدیریت می‌کند (بدون کانتینر برای استقرار، بدون بسته برای نصب محلی)
  2. پخش پیش‌رونده : stream=True یک جعبه سیاه ۹۰ ثانیه‌ای را به یک فید زنده از فراخوانی‌های ابزار و تکه‌های متن تبدیل می‌کند.
  3. منابع درون‌خطی : نصب AGENTS.md ، SKILL.md و اسکریپت‌های از پیش ساخته شده در sandbox بدون هیچ مرحله آپلود یا استقرار
  4. مهار کشف خودکار : فایل‌های قرار داده شده در .agents/ به طور خودکار انتخاب می‌شوند (نیازی به پیکربندی SDK نیست)
  5. حالت دوبعدی : environment_id فایل‌ها و بسته‌ها را ردیابی می‌کند؛ previous_interaction_id زمینه مکالمه را ردیابی می‌کند؛ هر کدام را می‌توان به طور مستقل ارسال کرد
  6. دانلود اسنپ‌شات : محیط یک فایل سیستم کامل tar است که از طریق Gemini Files API قابل دسترسی است.
  7. عامل‌های نامگذاری‌شده : agents.create() پیکربندی را به‌طور دائم ذخیره می‌کند؛ فراخوانی‌های بعدی فقط شناسه عامل و environment="remote" را بدون هیچ منبعی ارسال می‌کنند.

ADK + Cloud Run در مقابل Managed Agents: تفاوت در یک نگاه

قابلیت

ADK + اجرای ابری

عامل‌های مدیریت‌شده در رابط برنامه‌نویسی نرم‌افزار Gemini

فراهم کردن یک سندباکس

docker build + gcloud run deploy

interactions.create()

تعریف ابزارها

توابع پایتون ثبت شده در عامل

داخلی: مرور وب، اجرای کد، سیستم فایل

نصب بسته‌ها

pip install در داکرفایل

عامل، pip install درون جعبه شنی اجرا می‌کند.

رویدادهای جریان

زیرساخت SSE سفارشی

stream=True

ادامه یک جلسه

پایگاه داده جلسه + تزریق زمینه

environment_id + previous_interaction_id

فایل‌های پیکربندی

کدنویسی ثابت در عامل یا تزریق در هنگام راه‌اندازی

از طریق environment.sources نصب شده است

زیرساخت برای مدیریت

کانتینر، Cloud Run، IAM، اسرار

هیچکدام

مراحل بعدی