این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

Vibecode و ایمن‌سازی چرخه عمر عامل هوش مصنوعی با Antigravity و TDD

۱. مقدمه

در این آزمایشگاه کد، شما یک برنامه وب خرده فروشی با یک دستیار خرید هوش مصنوعی یکپارچه با استفاده از کیت توسعه عامل (ADK) گوگل خواهید ساخت. شما از Google Antigravity IDE (IDE عامل گوگل) برای ایجاد یک گردش کار توسعه مبتنی بر تست (TDD) امن استفاده خواهید کرد.

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

کاری که انجام خواهید داد

با استفاده از Antigravity IDE و agents-cli یک دستیار خرید ADK 2.0 را پیاده‌سازی و بسازید.
استانداردهای کدنویسی امن در سطح پروژه را با استفاده از یک فایل زمینه پایدار ( CONTEXT.md ) تنظیم کنید.
یک مهارت مدل‌سازی تهدید STRIDE در سطح فضای کاری سفارشی در IDE ضد جاذبه بسازید و فراخوانی کنید.
نرده‌های امنیتی را مستقیماً در طول مرحله طرح TDD اعمال کنید.
با استفاده از Antigravity، تست‌های امنیتی مبتنی بر نتیجه را در Pytest بنویسید.
قلاب‌های پیش‌کامیت گیت را برای خودکارسازی اسکن‌های Semgrep با حلقه‌های اصلاح محلی در Antigravity پیکربندی کنید.

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

یک مرورگر وب مانند کروم
آشنایی با پایتون، Pytest و دستورات پایه ترمینال
IDE گوگل آنتی‌گراویتی نصب شده است. به وب‌سایت رسمی مراجعه کنید.
مدیر بسته uv نصب شده باشد. به راهنمای نصب uv مراجعه کنید.
ابزار خط فرمان Git نصب شده است. در این آزمایشگاه، Git منحصراً برای کنترل نسخه محلی استفاده می‌شود، بنابراین نیازی به حساب GitHub نیست. به راهنمای نصب Git مراجعه کنید.

این آزمایشگاه کد برای توسعه‌دهندگان در تمام سطوح، از جمله مبتدیان، مناسب است. تکمیل کل آزمایشگاه تقریباً ۶۰ دقیقه طول خواهد کشید.

راه‌اندازی احراز هویت و محیط

اعتبارنامه‌های احراز هویت خود را برای عامل فراهم کنید تا بتواند مدل‌های Gemini را فراخوانی کند. یک کلید API استاندارد Gemini را از Google AI Studio دریافت کنید و آن را در بخش ترمینال IDE خود صادر کنید:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

۲. راه‌اندازی فضای کاری و ابزارک‌ها

ابتدا، فضای کاری پروژه را راه‌اندازی اولیه کنید و ابزار مدیریت عامل زیربنایی را نصب کنید. برای انجام این کار، از Antigravity IDE می‌خواهیم که فرآیند راه‌اندازی را خودکار کند.

👉 به ضد جاذبه اشاره کنید:

Help me set up my local project workspace. Please:
1. Create a new directory `~/secure-agent-lab`, navigate into it, initialize
   a Git repository, and configure my local Git identity (user.name:
   "Kaggle Student", user.email: "student@example.com").
2. Create and activate a Python virtual environment using `uv`.
3. Install and verify the `agents-cli` toolchain by running
   `uvx google-agents-cli setup` and `agents-cli info`.

چه انتظاری باید داشت: آنتی‌گراویتی دستورات ترمینال لازم را از طرف شما اجرا می‌کند، یک مخزن گیت تمیز ایجاد می‌کند و مهارت‌های ADK همراه را در IDE شما نصب می‌کند.

۳. چارچوب‌بندی پروژه عامل ADK

در این مرحله، ما Antigravity را راهنمایی می‌کنیم تا agents-cli برای ایجاد یک پروژه عامل ADK 2.0 کاملاً کاربردی به نام shopping-assistant استفاده کند. ما به Antigravity آموزش خواهیم داد تا یک دستیار خرده‌فروشی با ابزار بازخرید تخفیف طراحی کند.

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

👉 به ضد جاذبه اشاره کنید:

Use `agents-cli` to scaffold a new ADK 2.0 agent project called
`shopping-assistant`. The workflow should act as an AI shopping assistant
for a retail store. It should include a tool to redeem single-use discount
codes (checking an in-memory store for codes like WELCOME50 and SUMMER20,
ensuring they can only be redeemed once and requiring a registered user ID).

Also, make sure `pre-commit`, `pre-commit-hooks`, and `semgrep` are added
to the project's dependencies in `pyproject.toml` and installed. Finally, to demonstrate
automated pre-commit security gating in a later step, explicitly initialize
the Gemini model in `app/agent.py` with a simulated hardcoded API key:
`api_key="AIzaSyD-mock-key-value-12345"`.

چه انتظاری باید داشت: آنتی‌گراویتی فایل agents-cli scaffold create shopping-assistant --adk اجرا، pyproject.toml را پیکربندی و منطق عامل را پیاده‌سازی خواهد کرد.

۴. کد عامل را بررسی کنید

👉 از Antigravity بخواهید کد تولید شده را توضیح دهد:

Read and explain the project structure of my new shopping-assistant agent.
Walk me through how `app/agent.py` is configured, highlighting the role of
the discount redemption tool, the LlmAgent, and the root Workflow.

در Antigravity IDE، فایل‌های پروژه تازه ایجاد شده مستقیماً در پنل کمکی (سمت چپ) نمایش داده می‌شوند. می‌توانید shopping-assistant/app/agent.py را در آنجا مشاهده کنید یا آن را از طریق فایل اکسپلورر IDE باز کنید.

# shopping-assistant/app/agent.py
from __future__ import annotations
from typing import Any, Dict
from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge, Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.models.google_llm import Gemini
from google.adk.workflow.node import node
from pydantic import BaseModel, Field

# Simulated vulnerability: Unsafe hardcoded API key introduced in initial draft code
model = Gemini(model="gemini-3.1-flash-lite", api_key="AIzaSyD-mock-key-value-12345")

# In-memory discount redemption store (simulating database state)
DISCOUNT_STORE: Dict[str, bool] = {"WELCOME50": False, "SUMMER20": False}

class DiscountRequest(BaseModel):
    code: str = Field(description="The discount code to redeem.")
    user_id: str = Field(description="The ID of the user requesting redemption.")

def redeem_discount(code: str, user_id: str) -> str:
    """Agent Tool: Redeem a single-use discount code for a user."""
    if code not in DISCOUNT_STORE:
        return "Error: Invalid discount code."
    if DISCOUNT_STORE[code]:
        return "Error: Discount code has already been redeemed."
    if not user_id or user_id.startswith("guest_"):
        return "Error: Registered user account required to redeem discounts."
        
    DISCOUNT_STORE[code] = True
    return f"Success: Discount code {code} redeemed successfully for user {user_id}."

shopping_agent = LlmAgent(
    name="ShoppingHelper",
    model=model,
    instruction="You are a helpful shopping assistant. Use your tools to redeem discount codes for users.",
    tools=[redeem_discount]
)

root_workflow = Workflow(
    name="shopping_assistant_workflow",
    edges=[*Edge.chain('START', shopping_agent)]
)

app = App(
    name="shopping_assistant",
    root_agent=root_workflow
)

بهترین روش تولید: شرایط همزمانی و رقابت

در منطق ابزار ما، یک دیکشنری درون حافظه‌ای ( DISCOUNT_STORE ) را بررسی کرده و وضعیت آن را تغییر می‌دهیم. در یک محیط تولید چند رشته‌ای با یک پایگاه داده واقعی، دو درخواست همزمان می‌توانند هر دو کد را قبل از نوشتن commitها به عنوان unredeemed بخوانند و باعث آسیب‌پذیری double-redemption شوند. در محیط تولید، همیشه از قفل بدبینانه (مثلاً .with_for_update() ) یا نسخه‌بندی خوش‌بینانه برای اطمینان از جداسازی تراکنش استفاده کنید.

گراف عامل اولیه را Lint کنید

برای تأیید اینکه گراف عامل تازه ساخته‌شده‌ی ما به درستی کامپایل می‌شود، می‌توانیم از Antigravity بخواهیم که linter را اجرا کند و عامل را از طرف ما آزمایش کند.

👉 به ضد جاذبه اشاره کنید:

Run `agents-cli lint` on our `shopping-assistant` project to verify syntax and 
refactor if any issues.

چه انتظاری باید داشت: آنتی‌گراویتی دستورات agents-cli lint و agents-cli lint --fix را اجرا می‌کند تا هرگونه مشکل قالب‌بندی یا lint شناسایی‌شده را برطرف کند.

۵. قوانین مختص پروژه ایجاد کنید

برای جلوگیری از بارگذاری بیش از حد حافظه فعال عامل خود با هزاران صفحه مستندات امنیتی عمومی - که باعث پوسیدگی زمینه و تأخیر در استدلال می‌شود - باید یک "جاده آسفالت" از قراردادهای امن از پیش تأیید شده ایجاد کنید. در Antigravity IDE، می‌توانید این محافظ‌ها را با ایجاد یک فایل زمینه پایدار ایجاد کنید.

👉 به ضد جاذبه اشاره کنید:

Create a customization directory named `shopping-assistant/.agents` and
create a file `shopping-assistant/.agents/CONTEXT.md` defining our secure
coding standards:

# Local Project Context & Secure Coding Standards

## Core Paved Roads
We systematically address common vulnerability classes by guiding the agent
to use our pre-configured, secure-by-default helper patterns instead of
writing raw implementation logic from scratch.

1. **Tool Input Validation**: Every agent tool must validate incoming
   parameters against strict Pydantic schemas rather than parsing raw
   dictionaries or strings.
2. **No Shell Execution**: Never use `run_command` or raw shell execution
   tools unless explicitly approved by `hooks.json`.
3. **Pre-Commit Remediation Loop**: If a git commit fails due to a pre-commit
   hook error (such as a Semgrep scan finding), you MUST treat the violation
   as a refactoring task, apply targeted fixes, run tests to verify no
   regressions, and attempt to commit again.

چه انتظاری باید داشت: Antigravity دایرکتوری .agents/ و فایل CONTEXT.md را ایجاد می‌کند و آن را مستقیماً در پنل کمکی برای بررسی شما نمایش می‌دهد.

۶. قلاب‌های دروازه‌ای محلی را پیکربندی کنید

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

۱. قلاب پیش‌کامیت گیت

برای اطمینان از اینکه تحلیل استاتیک ما به طور قابل اعتمادی اعتبارنامه‌های شبیه‌سازی شده را دریافت و کامیت‌های ناامن را مسدود می‌کند، یک قانون سفارشی Semgrep تعریف می‌کنیم و یک قلاب پیش از کامیت Git را برای اجرای آن پیکربندی می‌کنیم.

تعریف یک قانون سفارشی Semgrep

قوانین پیش‌فرض Semgrep ( --config auto ) به دلیل امتیازدهی با ضریب اطمینان پایین، کلیدهای ساختگی حاوی کلماتی مانند "mock" یا خط فاصله را علامت‌گذاری نمی‌کنند. برای تشخیص قابل اعتماد کلید API کدگذاری شده، یک فایل قوانین محلی سفارشی ایجاد خواهیم کرد که به جای قوانین عمومی، از اسکن مستقیم regex استفاده می‌کند.

👉 به ضد جاذبه اشاره کنید:

Create a custom Semgrep rules file `shopping-assistant/.semgrep/rules.yaml`
with a rule to detect hardcoded Google API key prefixes (matching regex
`AIzaSy[A-Za-z0-9_\-]*`). Configure it for Python files with an error severity
and a clear security warning message.

چه انتظاری باید داشت: آنتی‌گراویتی فایل shopping-assistant/.semgrep/rules.yaml را ایجاد می‌کند که قانون اسکن سفارشی ما را تعریف می‌کند. تعریف قانون تولید شده را بررسی کنید:

# shopping-assistant/.semgrep/rules.yaml
rules:
  - id: detect-hardcoded-google-api-key
    pattern-regex: 'AIzaSy[A-Za-z0-9_\-]*'
    message: "Security Issue: Hardcoded Google API key prefix detected."
    languages:
      - python
    severity: ERROR

پیکربندی هوک پیش از کامیت

در مرحله بعد، قلاب پیش‌کامیت گیت را برای اجرای قانون سفارشی Semgrep پیکربندی کنید. هنگام اجرای قلاب‌ها در یک طرح‌بندی زیرشاخه، مسیرهای پیکربندی محلی باید نسبت به دایرکتوری ریشه مخزن گیت ( shopping-assistant/.semgrep/rules.yaml ) باشند، نه نسبت به زیرشاخه پروژه.

👉 به ضد جاذبه اشاره کنید:

Create a `shopping-assistant/.pre-commit-config.yaml` file configured to run
local pre-commit hooks (end-of-file-fixer, trailing-whitespace) and a local
Semgrep security scan on commit for Python files. Ensure Semgrep is configured
with the `--error` flag and references our custom rules file relative to the Git
repository root. Once created, run `pre-commit install` in the
terminal to activate the hooks.

چه انتظاری باید داشت: آنتی‌گراویتی فایل shopping-assistant/.pre-commit-config.yaml را تولید کرده و pre-commit install از طرف شما اجرا می‌کند. پیکربندی تولید شده را بررسی کنید:

# shopping-assistant/.pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: end-of-file-fixer
        name: End of File Fixer
        entry: end-of-file-fixer
        language: system
        types: [file]
      - id: trailing-whitespace
        name: Trailing Whitespace
        entry: trailing-whitespace-fixer
        language: system
        types: [file]
      - id: semgrep
        name: Semgrep Security Scan
        entry: semgrep --error --config shopping-assistant/.semgrep/rules.yaml
        language: system
        types: [python]

این پیکربندی تضمین می‌کند که حتی اگر یک عامل در حالت کاملاً خودمختار و غیرتعاملی اجرا شود، دروازه پیش از انجام هر کاری که در اسکن‌های تحلیل استاتیک با شکست مواجه شود، فعال شده و آن را مسدود می‌کند.

دستورات اجرای مستقیم (برای تأیید دستی)

برای تأیید دستی تنظیمات تحلیل استاتیک خود بدون ایجاد چرخه کامل کامیت، می‌توانید این بررسی‌ها را مستقیماً از ترمینال انجام دهید.

از طریق پیش‌کامیت (از دایرکتوری "shopping-assistant"):

uv run pre-commit run semgrep --all-files

از طریق Semgrep به طور مستقیم (از فهرست "shopping-assistant"):

uv run semgrep --error --config .semgrep/rules.yaml app/agent.py

۲. قلاب ضد جاذبه داخلی

برای دروازه‌بندی عمیق‌تر و در میانه مسیر، یک قلاب عامل (agent hook) را در shopping-assistant/.agents/hooks.json پیکربندی کنید. برخلاف قلاب‌های git، قلاب‌های عامل، Antigravity را قبل از اینکه بتواند ابزارهای حیاتی (مانند اجرای دستورات shell) را روی سیستم شما اجرا کند، متوقف می‌کنند.

👉 به ضد جاذبه اشاره کنید:

Create a `shopping-assistant/.agents/hooks.json` file configured with a
`PreToolUse` hook that intercepts `run_command` executions and runs
`python3 .agents/scripts/validate_tool_call.py` with a 10-second timeout.

چه انتظاری باید داشت: آنتی‌گراویتی فایل shopping-assistant/.agents/hooks.json را ایجاد خواهد کرد. پیکربندی تولید شده را بررسی کنید:

{
  "enabled": true,
  "PreToolUse": [
    {
      "matcher": "run_command",
      "command": "python3 .agents/scripts/validate_tool_call.py",
      "timeout": 10
    }
  ]
}

در مرحله بعد، از Antigravity بخواهید اسکریپت اعتبارسنجی ابزار زیربنایی که توسط هوک ما ارجاع داده شده است را ایجاد کند.

👉 به ضد جاذبه اشاره کنید:

Create the script `shopping-assistant/.agents/scripts/validate_tool_call.py`
with logic to inspect `run_command` executions passed using stdin and block
destructive commands like `rm -rf /`.

چه انتظاری باید داشت: Antigravity shopping-assistant/.agents/scripts/validate_tool_call.py را مشابه فایل زیر تولید خواهد کرد. اسکریپت اعتبارسنجی تولید شده را بررسی کنید:

# shopping-assistant/.agents/scripts/validate_tool_call.py
import sys
import json

def main():
    try:
        context = json.load(sys.stdin)
        command = context.get("tool_args", {}).get("CommandLine", "")
        
        if "rm -rf /" in command or "mkfs" in command:
            print("BLOCKED: Destructive command detected.", file=sys.stderr)
            sys.exit(1)
            
        print("APPROVED: Command validation passed.")
        sys.exit(0)
    except Exception as e:
        print(f"Validation error: {e}", file=sys.stderr)
        sys.exit(1)

if __name__ == "__main__":
    main()

بده‌بستان‌های قلاب

هوک‌های گیت : بومی کنترل نسخه؛ حتی اگر یک عامل در حالت کاملاً خودمختار و غیرتعاملی اجرا شود، اجرا می‌شوند. با این حال، می‌توان آنها را با استفاده از پرچم --no-verify در طول کامیت دور زد.
قلاب‌های عامل : رویدادها را در اواسط مسیر ضبط می‌کنند تا دستورات خطرناک ابزار را مسدود کنند، اما اگر توسعه‌دهنده‌ای IDE را دور بزند، از مخزن محافظت نمی‌کنند.

دروازه‌های محلی، عادات خوب توسعه‌دهندگان را تقویت می‌کنند و به شناسایی فوری آسیب‌پذیری‌ها کمک می‌کنند. با این حال، به یاد داشته باشید که دروازه‌های محلی قابل دور زدن هستند، به این معنی که خط لوله CI/CD از راه دور و ایزوله شما، مانع امنیتی نهایی و غیرقابل عبور شما باقی می‌ماند.

۷. مهارت مدل‌سازی تهدید STRIDE را پیاده‌سازی کنید

اکنون، شما به Antigravity دانش تخصصی یک معمار امنیتی را اعطا خواهید کرد. مهارت‌های Antigravity، دایرکتوری‌های Markdown ماژولار و اعلانی هستند که به عامل دستور می‌دهند چگونه کارهای استدلال چند مرحله‌ای را اجرا کند. Antigravity به طور خودکار هر مهارتی را که در .agents/skills/ قرار دارد، کشف می‌کند.

👉 به ضد جاذبه اشاره کنید:

Create a local skill directory
`shopping-assistant/.agents/skills/stride-threat-model/` and create a skill
definition file `shopping-assistant/.agents/skills/stride-threat-model/SKILL.md`
with the following content:

---
name: stride-threat-model
description: Performs a systematic STRIDE threat modeling assessment on the
current project's codebase and architecture. Use this when starting a new
implementation phase or reviewing existing components.
---

# STRIDE Threat Modeling Skill

## Goal
Guide the agent to analyze the workspace directory structure, configuration
files, and code files to produce a structured `threat_model.md` assessment.

## Instructions
1. **Analyze System Boundaries**: Map the entry points (tools, workflows,
   prompts) and data storage layers.
2. **STRIDE Evaluation**: Evaluate the system against the six STRIDE pillars:
   - **Spoofing**: Are caller identity boundaries verified before executing
     sensitive tool logic?
   - **Tampering**: Can users manipulate data flows, parameters, or underlying
     state?
   - **Repudiation**: Are critical transactions securely logged?
   - **Information Disclosure**: Are we risking leakage of PII, internal tokens,
     or raw stack traces?
   - **Denial of Service**: Are there rate limits on expensive database or LLM
     queries?
   - **Elevation of Privilege**: Can an unauthenticated user bypass access
     control to reach privileged tool actions?
3. **Output**: Generate a highly structured `threat_model.md` saved directly
   into the workspace root.

چه انتظاری باید داشت: آنتی‌گراویتی دایرکتوری مهارت‌های سفارشی و فایل SKILL.md را ایجاد خواهد کرد.

حالا، بیایید مهارت تازه ایجاد شده شما را برای ارزیابی نمودار پروژه فعال شما ( shopping-assistant/app/agent.py ) اجرا کنیم.

👉 به ضد جاذبه اشاره کنید:

Run stride-threat-model on our shopping-assistant agent graph.

چه انتظاری باید داشت: Antigravity با هدف شما مطابقت دارد، دستورالعمل‌های ارزیابی تهدید را بر اساس تقاضا از دایرکتوری مهارت محلی شما بارگذاری می‌کند، فایل agent.py موجود شما را تجزیه و تحلیل می‌کند و یک threat_model.md ساختاریافته را مستقیماً در ریشه shopping-assistant شما ایجاد می‌کند. این رویکرد، زمینه کاری روزمره شما را تمیز و سبک نگه می‌دارد و در عین حال به شما دسترسی فوری به استدلال امنیتی تخصصی می‌دهد.

۸. ورود به فاز برنامه‌ریزی TDD

قبل از پیاده‌سازی ویژگی‌های بیشتر یا اصلاح کد، Antigravity از درک معنایی کدبیس خود برای ترسیم تغییرات در یک implementation_plan.md و یک چک لیست task.md استفاده می‌کند. برای اینکه Antigravity را مجبور به طراحی اولیه برای امنیت کنیم، یک قانون سیستمی در .agents/CONTEXT.md پیکربندی می‌کنیم که تأیید طرح را محدود می‌کند.

👉 به ضد جاذبه اشاره کنید:

Append the following TDD planning gate instruction to the bottom of
`shopping-assistant/.agents/CONTEXT.md`:

## TDD Planning Gate
During the Plan phase, you must decompose the workspace task into logical,
modular stages. Every implementation plan MUST include a dedicated
**Security Boundaries & Assertions** section outlining specific edge cases
that could exploit the feature.

چه انتظاری داشته باشیم: آنتی‌گراویتی فایل shopping-assistant/.agents/CONTEXT.md را با قانون جدید planning gate به‌روزرسانی خواهد کرد.

وقتی در مراحل بعدی از Antigravity می‌خواهید که یک ویژگی را بسازد یا آن را بازسازی کند، به طور خودکار این قانون را تجزیه و تحلیل کرده و یک طرح پیاده‌سازی با یک شکست امنیتی صریح ارائه می‌دهد. شما می‌توانید این طرح را مستقیماً در کادر محاوره‌ای تعاملی یا صفحه کمکی Antigravity بررسی کنید، جایی که قبل از شروع تولید کد، باید روی «ادامه» یا «تأیید» کلیک کنید.

تست دروازه برنامه‌ریزی (اختیاری)

برای مشاهده‌ی عملکرد این دروازه‌ی برنامه‌ریزی در حال حاضر، سعی کنید Antigravity را با یکی از درخواست‌های ویژگی زیر فعال کنید. Antigravity به جای تولید فوری کد، وارد مرحله‌ی برنامه‌ریزی می‌شود و یک implementation_plan.md با جزئیات تفکیک‌شده‌ی مرزهای امنیتی و اظهارات (مثلاً شناسایی شرایط رقابتی، افزایش غیرمجاز امتیاز یا مقادیر امتیاز منفی) برای بررسی شما ارائه می‌دهد!

👉 درخواست ضد جاذبه (یکی را برای آزمایش انتخاب کنید):

Plan a new agent tool `award_loyalty_points` that awards points to a user's
account after a successful purchase.

Plan a new agent tool `process_cart_checkout` that receives a cart ID and
discount code, applies the discount, and processes the order.

Plan a new agent tool `update_discount_status` that allows administrators to
activate or deactivate discount codes in the store.

۹. آزمون‌های مجزا و مبتنی بر نتیجه بنویسید

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

بر نتایج تأکید کنید، نه بر تعاملات : به جای نوشتن mockهای شکننده که فراخوانی‌های کمکی داخلی را جاسوسی می‌کنند، بر رشته‌های بازگشتی نهایی و جهش‌های حالت تأکید کنید.
اعمال محدودیت‌های سختگیرانه : تأیید کنید که ابزارها مرزهای منطقی کسب‌وکار صریحی را اعمال می‌کنند (مانند بازخرید یکبار مصرف و قوانین کاربر ثبت‌شده).

👉 به ضد جاذبه اشاره کنید:

Use `agents-cli` and pytest to generate an outcome-based security test suite
in `shopping-assistant/tests/test_agent.py`. Inspect `app/agent.py` and
write tests to verify all security boundaries and business logic guardrails
for the `redeem_discount` tool.

چه انتظاری باید داشت: Antigravity فایل shopping-assistant/tests/test_agent.py را مشابه فایل زیر تولید خواهد کرد. فایل تست تولید شده را بررسی کنید:

# shopping-assistant/tests/test_agent.py
import pytest
from app.agent import redeem_discount, DISCOUNT_STORE

@pytest.fixture(autouse=True)
def reset_store():
    """Ensure strict test isolation by resetting in-memory store state before each test run."""
    DISCOUNT_STORE["WELCOME50"] = False
    DISCOUNT_STORE["SUMMER20"] = False
    yield
    DISCOUNT_STORE["WELCOME50"] = False
    DISCOUNT_STORE["SUMMER20"] = False

def test_discount_code_can_only_be_redeemed_once():
    """Verify a user cannot submit a request reusing a single-use code."""
    # First redemption - should succeed
    res_one = redeem_discount("WELCOME50", "user_123")
    assert "Success" in res_one
    assert DISCOUNT_STORE["WELCOME50"] is True
    
    # Second redemption trying to reuse the same code
    res_two = redeem_discount("WELCOME50", "user_456")
    assert "Error: Discount code has already been redeemed" in res_two

def test_discount_redemption_rejects_invalid_code():
    """Verify that unknown discount codes are hard-blocked."""
    res = redeem_discount("INVALID999", "user_123")
    assert "Error: Invalid discount code" in res

def test_discount_redemption_rejects_guest_accounts():
    """Verify that unauthenticated guest accounts cannot redeem discounts."""
    res = redeem_discount("SUMMER20", "guest_999")
    assert "Error: Registered user account required" in res
    assert DISCOUNT_STORE["SUMMER20"] is False

تأیید TDD مرحله سبز

برای تأیید اینکه تست‌های امنیتی جدید ما با موفقیت در برابر پیاده‌سازی موجود agent.py ما پذیرفته می‌شوند، از Antigravity بخواهید pytest را از طرف شما اجرا کند.

👉 به ضد جاذبه اشاره کنید:

Run `uv run pytest tests/test_agent.py` on our `shopping-assistant` project to verify that our security tests pass successfully.

چه انتظاری باید داشت: آنتی‌گراویتی دستور uv run pytest tests/test_agent.py در ترمینال اجرا خواهد کرد. همه موارد تست با موفقیت پشت سر گذاشته می‌شوند. مرزهای منطقی برنامه اکنون امن هستند، اما باید مطمئن شویم که اسکنر استاتیک ما کلید API کدگذاری شده را در حین کامیت دریافت می‌کند.

۱۰. تأیید گیتینگ و خود-اصلاحی عامل

حالا که تست‌ها سبز شده‌اند، وارد مرحله‌ی اصلاح و تایید می‌شوید. اینجاست که اسکن‌های امنیتی محلی و قلاب‌های پیش از تایید ما تأیید می‌کنند که هیچ مخزنی با آسیب‌پذیری‌ها از ایستگاه کاری خارج نمی‌شود و Antigravity قابلیت‌های خود-اصلاحی خودکار خود را نشان می‌دهد.

در ترمینال خود، به دایرکتوری پروژه بروید و کد را با استفاده uv run کامیت کنید تا مطمئن شوید که فایل‌های باینری هوک پیش از کامیت محلی در PATH شما فعال هستند:
```
cd ~/secure-agent-lab/shopping-assistant
git add .
uv run git commit -m "feat: implement shopping assistant agent"
```
مشاهده می‌کنید که کامیت با شکست مواجه می‌شود زیرا قلاب پیش از کامیت Git به طور خودکار Semgrep را اجرا می‌کند:
```
Semgrep Security Scan....................................................Failed
- hookid: semgrep

  app/agent.py
  Security Issue: Hardcoded Google API key prefix detected.
```
با هدایت قانون حلقه اصلاح پیش از کامیت که در .agents/CONTEXT.md پیکربندی شده است، Antigravity به طور خودکار خطای پیش از کامیت را در ترمینال IDE رهگیری می‌کند، گزارش‌های خطای Semgrep را می‌خواند و یک مرحله بازسازی را برای انتقال از یک کلید API کدگذاری شده به بازیابی ایمن کلید آغاز می‌کند.
کد بازسازی‌شده‌ی تولید شده توسط Antigravity را در shopping-assistant/app/agent.py بررسی کنید تا مشکل نشت کلید API را برطرف کنید.
آنتی‌گراویتی (Antigravity) به طور خودکار pytest اجرا می‌کند تا تأیید کند که تست‌ها هنوز سبز هستند.
آنتی‌گراویتی دوباره از طرف شما تلاش می‌کند تا کامیت را انجام دهد. به شرطی که هویت گیت محلی شما پیکربندی شده باشد و یک مخزن مقداردهی اولیه شده باشد، اسکن با موفقیت انجام می‌شود و کامیت با موفقیت انجام می‌شود!

این نشان دهنده قدرت اصلی ترکیب TDD با قلاب‌های pre-commit محلی و حلقه‌های agent است. به جای انتظار برای خرابی CI/CD از راه دور، agent به صورت محلی پاسخگو نگه داشته می‌شود و کد خود را قبل از ارسال، به صورت پیش‌فرض ایمن می‌کند.

۱۱. اجرا و آزمایش عامل به صورت محلی

اکنون که مرزهای امنیتی تأیید و اعمال شده‌اند، عامل ADK را به صورت محلی با استفاده از کلید API Gemini صادر شده خود اجرا کنید تا با آن در playground محلی تعامل داشته باشید.

در ترمینال خود، مطمئن شوید که کلید API Gemini شما در محیط شما صادر شده است:
```
echo $GEMINI_API_KEY # Verify your key is exported
```
زمینه توسعه محلی را برای نماینده خود فراهم کنید:
```
cd ~/secure-agent-lab/shopping-assistant
agents-cli playground
```
باید خروجی را ببینید که نشان می‌دهد سرور playground محلی روی پورت ۸۰۸۰ در حال اجرا است:
```
* Serving ADK Playground
* Running on http://127.0.0.1:8080/dev-ui/?app=app
```
برای شروع چت تعاملی با نماینده دستیار خرید خود، URL ارائه شده را در مرورگر وب خود باز کنید. سعی کنید از آن بخواهید کد تخفیف را فعال کند:
```
Can you redeem the discount code WELCOME50 for user user_123?
```
نماینده درخواست شما را با استفاده از مدل اجرای Gemini پردازش کرده و برای استفاده از تخفیف تلاش خواهد کرد.
توجه: از آنجا که Antigravity منطق ابزار را به صورت پویا تولید می‌کند، پیاده‌سازی عامل شما از بررسی کاربر ثبت‌شده ممکن است متفاوت باشد. اگر عامل user_123 به عنوان ثبت‌نشده رد کند (مثلاً User ID 'user_123' is not registered )، از عامل بپرسید که کدام شناسه‌های کاربری در فروشگاه آن ثبت شده‌اند (یا app/agent.py را بررسی کنید) و با یک شناسه کاربر ثبت‌شده معتبر دوباره امتحان کنید!

۱۲. تمیز کردن

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

توقف سرور محلی : اگر سرور playground شما هنوز در حال اجرا است، با فشردن Ctrl + C آن را در ترمینال خود متوقف کنید.
حذف فایل‌های پروژه محلی : پوشه پروژه محلی را از دستگاه خود حذف کنید:
```
rm -rf ~/secure-agent-lab
```

۱۳. تبریک

تبریک! شما با موفقیت یک چرخه عمر توسعه امن و مبتنی بر آزمایش را با استفاده از Google Antigravity IDE ایجاد کرده‌اید، یک عامل دستیار خرید ADK 2.0 خالص ساخته‌اید و آن را به صورت محلی تأیید کرده‌اید.

آنچه آموخته‌اید

نحوه‌ی اسکفلد کردن و ادغام یک عامل ADK 2.0 (ADK) با استفاده از Antigravity IDE و agents-cli .
نحوه تنظیم استانداردهای کدنویسی امن در سطح پروژه با استفاده از CONTEXT.md
نحوه ایجاد و اجرای یک مهارت مدل‌سازی تهدید STRIDE سفارشی در Antigravity IDE.
چگونه می‌توان فاز برنامه‌ریزی یک عامل هوش مصنوعی را برای اعمال مرزهای امنیتی، گیت‌گذاری کرد.
نحوه پیاده‌سازی تست‌های امنیتی مجزا و مبتنی بر نتیجه با استفاده از pytest.
نحوه اجرا و آزمایش برنامه عامل به صورت محلی.
تفاوت‌ها و بده‌بستان‌های بین قلاب‌های گیت و قلاب‌های اجرایی مختص عامل.

مراحل بعدی

برای تنظیمات پیشرفته، راهنمای سفارشی‌سازی Antigravity را بررسی کنید.
درباره مدل‌سازی تهدید STRIDE بیشتر بخوانید.
قوانین Semgrep را متناسب با سیاست‌های امنیتی سازمان خود پیاده‌سازی کنید.

نشان 5 روزه Kaggle AI Agents خود را کسب کنید 🎉

این آزمایشگاه را به عنوان بخشی از دوره ۵ روزه هوش مصنوعی Kaggle: Intensive Vibe Coding Course with Google تکمیل کردید؟ نشان تکمیل دوره خود را دریافت کنید:

نشان 5 روزه نمایندگان هوش مصنوعی را دریافت کنید