agents.yaml

version: 1.0
agents:
  - name: A2a Orchestrator
    description: 作為協調代理，依官方A2A協定調度研究、分析與寫作子代理，整合結果交付。
    code_ref: workspace/python/agents/a2a-orchestrator
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: check_agent_availability
        type: FunctionTool
        description: 向遠端代理的 agent-card URL 發送一個 HTTP GET 請求，確認代理伺服器是否正在運行且可存取。
      - name: log_coordination_step
        type: FunctionTool
        description: 在複雜的多代理工作流程中，此函式提供了一個簡單的方法來記錄協調器在每個階段的行為，方便開發者追蹤流程。
    generate_content_config:
      temperature: 0.5
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - a2a
      - orchestrator
      - fastapi
    sub_agents:
      - name: Research Specialist
        description: 進行網路研究與事實查核。
        type: RemoteA2aAgent
        models:
          - gemini-2.0-flash
        tools:
          - name: research_topic
            type: FunctionTool
            description: 研究特定主題並提供詳細的發現。
          - name: fact_check
            type: FunctionTool
            description: 對特定的聲明或陳述進行事實查核。
        generate_content_config:
          temperature: 0.3
          max_output_tokens: 1500
        server-port: 8001
        tags:
          - to_a2a
          - research
          - fact-checking
          - fastapi
      - name: Content Writer
        description: 創作書面內容與摘要。
        type: RemoteA2aAgent
        models:
          - gemini-2.0-flash
        tools:
          - name: create_content
            type: FunctionTool
            description: 根據指定的類型與主題創作各種類型的內容。
          - name: format_content
            type: FunctionTool
            description: 將現有內容格式化為特定的格式或樣式。
        generate_content_config:
          temperature: 0.7
          max_output_tokens: 2000
        server-port: 8003
        tags:
          - to_a2a
          - writing
          - content-creation
          - fastapi
      - name: Analysis Agent
        description: 您是一位專注於從資訊與資料中提取洞察的資料分析專家。
        type: RemoteA2aAgent
        models:
          - gemini-2.0-flash
        tools:
          - name: analyze_data
            type: FunctionTool
            description: 分析資料並產生洞察與建議。
          - name: generate_insights
            type: FunctionTool
            description: 針對特定主題產生策略性洞察與建議。
        generate_content_config:
          temperature: 0.4
          max_output_tokens: 1500
        server-port: 8002
        tags:
          - to_a2a
          - analysis
          - data-insights
          - fastapi
  - name: ADK Interactions Agent
    description: 一個展示 Interactions API 整合的 ADK 代理，具備天氣、計算和搜尋工具。
    code_ref: workspace/python/agents/adk-interactions-integration
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: get_current_weather
        type: FunctionTool
        description: 取得特定地點的目前天氣。
      - name: calculate_expression
        type: FunctionTool
        description: 安全地計算數學表達式。
      - name: search_knowledge_base
        type: FunctionTool
        description: 在知識庫中搜尋資訊。
    server-port: 8000
    tags:
      - use_interactions_api
      - gemini
      - model
      - agent-factory
  - name: Artifact Agent
    description: 您是一個具備 Artifacts 儲存功能的進階文件處理代理程式。
    code_ref: workspace/python/agents/artifact-agent
    type: Agent
    models:
      - gemini-1.5-flash
    tools:
      - name: extract_text_tool
        type: FunctionTool
        description: 將文件文字提取並儲存為Artifacts。
      - name: summarize_document_tool
        type: FunctionTool
        description: 生成文件摘要並將其儲存為Artifacts。
      - name: translate_document_tool
        type: FunctionTool
        description: 將文件文字翻譯成目標語言並儲存為Artifacts。
      - name: create_final_report_tool
        type: FunctionTool
        description: 在知識庫中搜尋資訊。
      - name: list_artifacts_tool
        type: FunctionTool
        description: 在知識庫中搜尋資訊。
      - name: load_artifact_tool
        type: FunctionTool
        description: 按檔名和可選的版本號載入特定Artifact。
      - name: load_artifacts_tool
        type: LoadArtifactsTool
        description: 用於對話式Artifacts存取的內建工具。
    server-port: 8000
    tags:
      - tool_context
      - artifacts
      - load_artifacts_tool
      - translate
      - summarize
      - extract_text
      - report
  - name: Best Practices Agent
    description: 展示安全性、效能、可靠性和可觀測性最佳實踐的生產就緒代理。
    code_ref: workspace/python/agents/best-practices-agent
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: validate_input_tool
        type: FunctionTool
        description: 透過綜合檢查驗證使用者輸入。
      - name: retry_with_backoff_tool
        type: FunctionTool
        description: 執行具有重試邏輯和指數退避的操作。
      - name: circuit_breaker_call_tool
        type: FunctionTool
        description: 使用斷路器保護呼叫外部服務。
      - name: cache_operation_tool
        type: FunctionTool
        description: 執行快取操作以進行效能最佳化。
      - name: batch_process_tool
        type: FunctionTool
        description: 批次處理多個項目以提升效率。
      - name: health_check_tool
        type: FunctionTool
        description: 執行綜合健康檢查。
      - name: get_metrics_tool
        type: FunctionTool
        description: 取得當前系統指標。
    server-port: 8000
    tags:
      - security
      - validation
      - reliability
      - resilience
      - performance
      - observability
      - monitoring
      - circuit-breaker
      - cache
      - batch-processing
  - name: Blog Creation Pipeline
    description: 從研究到發布的完整部落格文章創建流水線。
    code_ref: workspace/python/agents/blog-pipeline
    type: SequentialAgent
    server-port: 8000
    tags:
      - sequential-workflow
      - pipeline
      - blog-creation
    sub_agents:
      - name: researcher
        description: 研究主題並收集關鍵資訊。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: research_findings
        tags:
          - research
      - name: writer
        description: 根據研究結果撰寫部落格文章草稿。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: draft_post
        tags:
          - writing
          - drafting
      - name: editor
        description: 審閱部落格文章草稿並提供編輯回饋。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: editorial_feedback
        tags:
          - editing
          - review
      - name: formatter
        description: 應用編輯回饋並格式化最終部落格文章。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: final_post
        tags:
          - formatting
          - markdown
  - name: Chuck Norris Agent
    description: 查克·諾里斯笑話助理，可以使用 OpenAPI 工具從查克·諾里斯 API 檢索笑話/事實。
    code_ref: workspace/python/agents/chuck-norris-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: get_random_joke
        type: OpenAPITool
        description: 取得隨機的查克·諾里斯笑話
      - name: search_jokes
        type: OpenAPITool
        description: 搜尋笑話
      - name: get_categories
        type: OpenAPITool
        description: 取得所有笑話類別
    server-port: 8000
    tags:
      - openapi
      - jokes
      - chuck-norris
      - open-api-toolset
  - name: Financial Calculator
    description: 具備 Python 程式碼執行能力的專業金融計算器
    code_ref: workspace/python/agents/code-calculator
    type: Agent
    models:
      - gemini-2.0-flash
    code_executor:
      name: builtin-code-executor
      type: BuiltInCodeExecutor
      description: 使用內建的 Python 程式碼執行器來進行精確的金融計算。
    generate_content_config:
      temperature: 0.1
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - financial-calculator
      - builtin-code-executor
      - python
      - precise-computation
  - name: Commerce Agent
    description: 一位個人運動購物禮賓，使用 Google Search Grounding 與儲存的使用者偏好來提供專家級產品推薦。此代理還展示了使用 SQLite 的會話持久性。
    code_ref: workspace/python/agents/commerce-agent-e2e
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: search_products
        type: AgentTool
        description: 使用帶有 Grounding 的 Google Search 搜尋體育產品。
      - name: save_preferences
        type: FunctionTool
        description: 為個人化推薦儲存使用者偏好 (運動、預算、經驗水平)。
      - name: get_preferences
        type: FunctionTool
        description: 檢索已儲存的使用者偏好。
    server-port: 8000
    tags:
      - commerce
      - google-search
      - preferences
      - session-persistence
      - sqlite
      - agent-tool
    sub_agents:
      - name: Product Search Agent
        description: 使用帶有 Grounding 的 Google Search 搜尋體育產品。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: google_search
            type: GoogleSearchAgentTool
            description: 一個包裝了僅使用 google_search 工具的子代理的工具。
        server-port: none
        tags:
          - google-search
          - search_products
          - grounding
  - name: Content Moderator
    description: 具備安全防護、驗證與監控功能的內容審查助理，展示適用於生產環境的回呼模式。
    code_ref: workspace/python/agents/content-moderator
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: generate_text
        type: FunctionTool
        description: 依指定主題與字數生成文字（示範版未串接真正模型）。
      - name: check_grammar
        type: FunctionTool
        description: 檢查語法並提供可能錯誤數（簡化示範：每 10 個字視為 1 個潛在問題）。
      - name: get_usage_stats
        type: FunctionTool
        description: 從狀態（state）中取得使用者統計資料，示範回呼如何累積指標。
    before_agent_callback:
      - name: before_agent_callback
        type: BeforeAgentCallback
        description: 1.[Before Agent]-這是最早執行的回呼，用於全域檢查與初始化。
    before_model_callback:
      - name: before_model_callback
        type: BeforeModelCallback
        description: 2.[Before Model]-這是內容安全的核心檢查點，可攔截不當請求並修改提示詞。
    before_tool_callback:
      - name: before_tool_callback
        type: BeforeToolCallback
        description: 3.[Before Tool]-工具層級的安全閘門，確保參數合法且使用量在限制內。
    after_tool_callback:
      - name: after_tool_callback
        type: AfterToolCallback
        description: 4.[After Tool]-工具結果的後處理與記錄點。
    after_model_callback:
      - name: after_model_callback
        type: AfterModelCallback
        description: 5.[After Model]-這是輸出過濾的關鍵點，確保回應內容符合隱私與安全標準。
    after_agent_callback:
      - name: after_agent_callback
        type: AfterAgentCallback
        description: 6.[After Agent]-最後執行的回呼，用於收尾與最終修改。
    server-port: 8000
    output_key: last_response
    tags:
      - callbacks
      - guardrails
      - validation
      - logging
      - pii-removal
      - metrics-tracking
      - security
      - content-moderation
  - name: Content Publisher
    description: 完整的內容發布系統，具有並行研究和循序創作功能
    code_ref: workspace/python/agents/content-publisher
    type: SequentialAgent
    server-port: 8000
    tags:
      - multi-agent
      - sequential-workflow
      - parallel-research
      - content-creation
    sub_agents:
      - name: ParallelResearch
        description: 同時執行所有研究管線
        type: ParallelAgent
        tags:
          - parallel-research
          - pipeline
        sub_agents:
          - name: NewsPipeline
            description: 取得並總結新聞
            type: SequentialAgent

            tags:
              - news

              - research

              - pipeline
            sub_agents:
              - name: news_fetcher
                description: 使用 Google 搜尋取得最新新聞文章
                type: Agent
                models:
                  - gemini-2.0-flash
                tools:
                  - name: google_search
                    type: GoogleSearchTool
                    description: 執行 Google 搜尋

                output_key: raw_news
                tags:
                  - news
                  - research
                  - fetch
              - name: news_summarizer
                description: 總結關鍵新聞要點
                type: Agent
                models:
                  - gemini-2.0-flash
                output_key: news_summary
                tags:
                  - news
                  - research
                  - summary
          - name: SocialPipeline
            description: 監控並分析社群媒體
            type: SequentialAgent
            tags:
              - social-media
              - research
              - pipeline
            sub_agents:
              - name: social_monitor
                description: 使用 Google 搜尋監控社群媒體趨勢
                type: Agent
                models:
                  - gemini-2.0-flash
                tools:
                  - name: google_search
                    type: GoogleSearchTool
                    description: 執行 Google 搜尋
                output_key: raw_social
                tags:
                  - social-media
                  - research
                  - monitor
              - name: sentiment_analyzer
                description: 分析社群情緒
                type: Agent
                models:
                  - gemini-2.0-flash
                output_key: social_insights
                tags:
                  - social-media
                  - research
                  - sentiment-analysis
          - name: ExpertPipeline
            description: 尋找並提取專家意見
            type: SequentialAgent
            tags:
              - expert
              - research
              - pipeline
            sub_agents:
              - name: expert_finder
                description: 使用 Google 搜尋尋找專家意見
                type: Agent
                models:
                  - gemini-2.0-flash
                tools:
                  - name: google_search
                    type: GoogleSearchTool
                    description: 執行 Google 搜尋
                output_key: raw_experts
                tags:
                  - expert
                  - research
                  - find
              - name: quote_extractor
                description: 提取可引用的見解
                type: Agent
                models:
                  - gemini-2.0-flash
                output_key: expert_quotes
                tags:
                  - expert
                  - research
                  - extract
      - name: article_writer
        description: 從所有研究撰寫文章草稿
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: draft_article
        tags:
          - writing
          - drafting
      - name: article_editor
        description: 編輯文章以提升清晰度和影響力
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: edited_article
        tags:
          - editing
          - review
      - name: article_formatter
        description: 格式化文章以供發布
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: published_article
        tags:
          - formatting
          - markdown
  - name: Context Compaction Agent
    description: 展示長對話上下文壓縮功能的代理
    code_ref: workspace/python/agents/context-compaction-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: summarize_text
        type: FunctionTool
        description: 用於摘要文字區塊的實用工具。
      - name: calculate_complexity
        type: FunctionTool
        description: 分析問題複雜度以決定回應深度。
    server-port: 8000
    tags:
      - context-compaction
      - conversation-summary
      - token-optimization
  - name: Custom Session Agent
    description: 演示 ADK 中自定義會話服務註冊模式
    code_ref: workspace/python/agents/custom-session-agent
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: describe_session_info
        type: FunctionTool
        description: 描述會話資訊的工具。
      - name: test_session_persistence
        type: FunctionTool
        description: 測試跨請求會話持久化的工具。
      - name: show_service_registry_info
        type: FunctionTool
        description: 顯示服務註冊表資訊的工具。
      - name: get_session_backend_guide
        type: FunctionTool
        description: 提供 Redis 作為會話後端的指南工具。
    server-port: 8000
    tags:
      - custom-session-service
      - redis
      - service-registry
      - factory-pattern
      - BaseSessionService
  - name: Customer Support
    description: 具備各種工具的客戶支援代理人
    code_ref: workspace/python/agents/customer-support
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: check_customer_status
        type: FunctionTool
        description: 檢查客戶是否為高級會員
      - name: log_interaction
        type: FunctionTool
        description: 記錄客戶互動以供存檔
      - name: get_order_status
        type: FunctionTool
        description: 透過 ID 取得訂單狀態
      - name: track_shipment
        type: FunctionTool
        description: 取得運送追蹤資訊
      - name: cancel_order
        type: FunctionTool
        description: 取消訂單（需要授權）
      - name: search_knowledge_base
        type: FunctionTool
        description: 搜尋技術文件
      - name: run_diagnostic
        type: FunctionTool
        description: 執行診斷測試
      - name: create_ticket
        type: FunctionTool
        description: 建立支援工單以進行升級處理
      - name: get_billing_history
        type: FunctionTool
        description: 檢索帳單歷史記錄
      - name: process_refund
        type: FunctionTool
        description: 處理退款（金額超過 $100 需要批准）
      - name: update_payment_method
        type: FunctionTool
        description: 更新儲存的付款方式
    generate_content_config:
      temperature: 0.5
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - customer-support
      - tools
      - yaml-config
      - visual-agent-builder
  - name: Customer Support Agent (AG-UI)
    description: 整合 AG-UI 的客戶支援 ADK 代理人。提供知識庫搜尋、訂單狀態查詢、支援工單建立、產品詳情查詢及退款處理（需人機協作）等功能。
    code_ref: workspace/python/agents/customer-support-agent
    type: Agent
    models:
      - gemini-2.0-flash-exp
    tools:
      - name: search_knowledge_base
        type: FunctionTool
        description: 搜尋知識庫以尋找相關資訊。
      - name: lookup_order_status
        type: FunctionTool
        description: 查詢客戶訂單的狀態。
      - name: create_support_ticket
        type: FunctionTool
        description: 為複雜問題建立支援工單。
      - name: get_product_details
        type: FunctionTool
        description: 從資料庫獲取產品詳情以生成產品卡片。
      - name: process_refund
        type: FunctionTool
        description: 處理訂單退款（需要前端使用者批准的人機協作）。
    server-port: 8000
    tags:
      - customer-support
      - ag-ui
      - fastapi
      - uvicorn
      - generative-ui
      - nextjs
  - name: Data Analysis Agent
    description: 具備視覺化與分析能力的智慧資料分析助理。
    code_ref: workspace/python/agents/data-analysis-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: analysis_agent
        type: AgentTool
        description: 具備統計工具的資料分析與見解代理。
        models:
          - gemini-2.0-flash
        tools:
          - name: analyze_column
            type: FunctionTool
            description: 分析資料集中的特定欄位。
          - name: calculate_correlation
            type: FunctionTool
            description: 計算兩個數值欄位之間的關聯性。
          - name: filter_data
            type: FunctionTool
            description: 依條件過濾資料集。
          - name: get_dataset_summary
            type: FunctionTool
            description: 取得目前資料集的摘要資訊。
        tags:
          - data-analysis
          - statistics
          - insights
      - name: visualization_agent
        type: AgentTool
        description: 使用 Python 程式碼執行生成資料視覺化。
        models:
          - gemini-2.0-flash
        code_executor:
          name: builtin-code-executor
          type: BuiltInCodeExecutor
          description: 使用內建的 Python 程式碼執行器來編寫生成並顯示視覺化的 Python 程式碼。
        tags:
          - data-visualization
          - code-executor
          - python
    server-port: 8000
    tags:
      - data-analysis
      - orchestrator
      - visualization
      - code-executor
      - data-visualization
      - statistics
  - name: Data Analysis Dashboard
    description: 整合 pandas 工具與 AG-UI 的數據分析 ADK Agent。提供 CSV 數據載入、統計分析及圖表生成功能，並透過 AG-UI 協議與 Vite+React 前端整合。
    code_ref: workspace/python/agents/data-analysis-dashboard
    type: Agent
    models:
      - gemini-2.0-flash-exp
    tools:
      - name: load_csv_data
        type: FunctionTool
        description: 將 CSV 數據載入記憶體以進行分析。
      - name: analyze_data
        type: FunctionTool
        description: 對載入的數據集執行統計分析。
      - name: create_chart
        type: FunctionTool
        description: 生成視覺化圖表數據。
    server-port: 8000
    tags:
      - data-analysis
      - dashboard
      - pandas
      - ag-ui
      - fastapi
      - visualization
      - reactjs
      - uvicorn
  - name: Deep Research Agent
    description: 提供高階介面，用於啟動背景研究任務、輪詢完成狀態、串流結果以及進行後續提問。
    code_ref: workspace/python/agents/deep-research-agent
    type: genai.Client
    models:
      - gemini-3-pro-preview
    tools:
      - name: research
        type: FunctionTool
        description: 執行完整的研究任務並返回結果。
      - name: research_with_format
        type: FunctionTool
        description: 使用特定的輸出格式執行研究。
      - name: follow_up
        type: FunctionTool
        description: 針對已完成的研究提出後續問題。
    init:
      api_key: YOUR_API_KEY_HERE
    server-port: none
    tags:
      - deep-research
      - interactions-api
      - google-genai
      - vertex-ai
      - background-task
      - polling
      - genai-client-interactions
      - background
  - name: Enterprise Lead Qualifier
    description: 具備公司情報和評分功能的企業銷售潛在客戶資格審查 Agent，用於企業規模的 Agent 管理、治理、編排與協作。
    code_ref: workspace/python/agents/enterprise-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: check_company_size
        type: FunctionTool
        description: 從企業資料庫查詢公司規模，可整合 CRM 系統或公司情報 API。
      - name: score_lead
        type: FunctionTool
        description: 根據公司規模、產業和預算等資格標準，將銷售潛在客戶評分 0-100。
      - name: get_competitive_intel
        type: FunctionTool
        description: 獲取將公司與競爭對手比較的競爭情報，可整合市場情報平台。
    server-port: 8000
    tags:
      - enterprise
      - sales
      - lead-qualification
      - crm
      - gemini-enterprise
      - production-ready
  - name: Essay Refinement System
    description: 一個完整的論文寫作和精煉系統，首先創建初稿，然後通過評論家-精煉者循環進行迭代改進。
    code_ref: workspace/python/agents/essay-refiner
    type: SequentialAgent

    server-port: 8000
    tags:
      - multi-agent
      - sequential-workflow
      - loop-agent
      - writing
      - refinement
      - essay
    sub_agents:
      - name: InitialWriter
        description: 撰寫論文的第一版草稿。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: current_essay
        tags:
          - writing
          - drafting
      - name: RefinementLoop
        description: 迭代評估和改進論文，直到滿足品質標準為止。
        type: LoopAgent
        generate_content_config:
          max_iterations: 5
        tags:
          - loop
          - iterative-improvement
          - quality-control
        sub_agents:
          - name: Critic
            description: 評估論文品質並提供具體的回饋。
            type: Agent
            models:
              - gemini-2.0-flash
            output_key: critique
            tags:
              - evaluation
              - feedback
              - critique
          - name: Refiner
            description: 根據評論者的回饋改進論文，或在論文被批准時退出循環。
            type: Agent
            models:
              - gemini-2.0-flash
            tools:
              - name: exit_loop
                type: FunctionTool
                description: 當論文被批准時，發出信號以終止精煉循環。
            output_key: current_essay
            tags:
              - refinement
              - editing
              - exit-condition
  - name: Finance Assistant
    description: |
      一個財務計算助手，可以協助：
      - 投資的複利計算
      - 抵押貸款或其他貸款的還款計算
      - 達到財務目標的每月儲蓄計算
      我可以同時執行多項計算以供比較。
      所有計算都包含詳細說明和格式化報告。
    code_ref: workspace/python/agents/finance-assistant
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: calculate_compound_interest
        type: FunctionTool
        description: 計算儲蓄或投資的複利。
      - name: calculate_loan_payment
        type: FunctionTool
        description: 使用標準攤銷公式計算每月貸款還款。
      - name: calculate_monthly_savings
        type: FunctionTool
        description: 計算達到財務目標所需的每月儲蓄。
    server-port: 8000
    tags:
      - finance
      - calculator
      - investment
      - loan
      - savings
      - asyncio
      - parallel
  - name: GEPA Optimization Agent
    description: GEPA 教學代理：模擬客服代理，展示如何使用 GEPA (遺傳演算法-帕雷托提示最佳化) 改善身份驗證、政策遵循和解釋清晰度。
    code_ref: workspace/python/agents/gepa-optimization-agent
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: verify_customer_identity
        type: BaseTool
        description: 透過檢查訂單號碼和電子郵件來驗證客戶身份。
      - name: check_return_policy
        type: BaseTool
        description: 驗證訂單是否在 30 天的退貨期限內。
      - name: process_refund
        type: BaseTool
        description: 為符合資格的客戶訂單處理退款。
    server-port: 8000
    tags:
      - gepa
      - customer-support
      - optimization
      - prompt-tuning
      - genetic-algorithm
      - base_tool
  - name: Grounding Agent
    description: 具有動態工具選擇功能的 Grounding 代理，可根據環境配置啟用網路搜尋與地圖 Grounding。
    code_ref: workspace/python/agents/grounding-agent
    type: Agent
    models:
      - gemini-2.0-flash
      - gemini-1.5-flash
    tools:
      - name: google_search
        type: GoogleSearchTool
        description: 執行 Google 搜尋以取得最新資訊。
      - name: google_maps_grounding
        type: GoogleMapsGroundingTool
        description: 處理基於位置的查詢和地圖 Grounding (在啟用 Vertex AI 時可用)。
      - name: analyze_search_results
        type: FunctionTool
        description: 分析搜尋結果並提取關鍵見解。
      - name: save_research_findings
        type: FunctionTool
        description: 將研究發現儲存為 Artifacts。
    generate_content_config:
      temperature: 0.3
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - grounding
      - google-search
      - google-maps
      - dynamic-tools
      - vertex-ai
      - research
      - analysis
      - grounding
  - name: Hello Agent
    description: 提供友善的對話體驗。 ADK 的入門範例，展示基礎代理的設定。
    code_ref: workspace/python/agents/hello-agent
    type: Agent
    models:
      - gemini-2.0-flash
    server-port: 8000
    tags:
      - hello-world
      - beginner
      - conversation
  - name: Interactions API Basic Agent
    description: 展示 Google Interactions API 的核心功能，包括基礎文字互動、伺服器端狀態管理、串流回應與函數呼叫。
    code_ref: workspace/python/agents/interactions-api-basic
    type: genai.Client
    models:
      - gemini-2.5-flash
      - gemini-2.5-pro
      - gemini-3-pro-preview
    tools:
      - name: create_basic_interaction
        type: FunctionTool
        description: 與 Gemini 模型建立單次的請求-回應互動。
      - name: create_stateful_conversation
        type: FunctionTool
        description: 建立具備伺服器端狀態管理的多輪對話。
      - name: create_streaming_interaction
        type: FunctionTool
        description: 建立即時回應輸出的串流互動。
      - name: create_function_calling_interaction
        type: FunctionTool
        description: 建立具備自定義函數呼叫能力的互動。
      - name: create_interaction_with_builtin_tools
        type: FunctionTool
        description: 使用內建工具 (如 google_search, code_execution) 建立互動。
    init:
      api_key: YOUR_API_KEY_HERE
    server-port: none
    tags:
      - interactions-api
      - google-genai
      - state-management
      - streaming
      - function-calling
      - standalone
  - name: Math Agent (OTel)
    description: 具有 OpenTelemetry 儀表化的 ADK 數學代理，展示使用 Jaeger 後端的分散式追蹤與結構化日誌。
    code_ref: workspace/python/agents/math-agent-otel
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: add_numbers
        type: FunctionTool
        description: 將兩個數字相加。
      - name: subtract_numbers
        type: FunctionTool
        description: 從 a 減去 b。
      - name: multiply_numbers
        type: FunctionTool
        description: 將兩個數字相乘。
      - name: divide_numbers
        type: FunctionTool
        description: 將 a 除以 b。
    server-port: 8000
    tags:
      - math
      - calculator
      - opentelemetry
      - otel
      - jaeger
      - tracing
      - observability
  - name: Host Agent (MCP/A2A)
    description: 將請求路由至 A2A 代理或 MCP 工具。
    code_ref: workspace/python/agents/mcp-a2a-master
    type: LlmAgent
    models:
      - gemini-2.5-flash
    tools:
      - name: _delegate_task
        type: FunctionTool
        description: 將任務委派給指定的代理。
      - name: _list_agents
        type: FunctionTool
        description: 回傳已註冊的 A2A 子代理的代理卡片物件字典列表。
      - name: terminal_server
        type: MCPToolset
        transports: stdio
        description: 提供與 MCP 伺服器通訊的工具集 (stdio)。
        tools:
          - name: run_command
            type: McpTool
            description: 在終端機中執行指令並回傳輸出。
      - name: arithmetic_server
        type: MCPToolset
        transports: streamable
        description: 提供與算術 MCP 伺服器通訊的工具集 (streamable)。
        tools:
          - name: add_numbers
            type: McpTool
            description: 將兩個數字相加並回傳結果。
    server-port: 8000
    tags:
      - mcp
      - a2a
      - orchestrator
      - router
      - stdio
      - streamable
    sub_agents:
      - name: Website Builder Simple
        protocol: a2a
        description: 此代理接收使用者關於建立網站的查詢，並生成一個包含嵌入式 CSS 和 JavaScript 的單一獨立 HTML 檔案。
        type: LlmAgent
        models:
          - gemini-2.0-flash-exp
        server-port: 8001
        tags:
          - website-builder
          - html
          - css
          - javascript
  - name: MCP File Assistant
    description: 具有檔案系統存取和人工介入迴路核准功能的 AI 助理。
    code_ref: workspace/python/agents/mcp-agent
    type: Agent
    models:
      - gemini-2.0-flash-exp
    tools:
      - name: '@modelcontextprotocol/server-filesystem'
        type: MCPToolset
        transports: stdio
        description: 提供與 MCP 伺服器通訊的工具集 (stdio)。
        tools:
          - name: read_file
            type: McpTool
            description: 讀取檔案內容 (無需核准)。
          - name: read_text_file
            type: McpTool
            description: 讀取文字檔案 (無需核准)。
          - name: list_directory
            type: McpTool
            description: 列出目錄內容 (無需核准)。
          - name: search_files
            type: McpTool
            description: 依模式搜尋檔案 (無需核准)。
          - name: get_file_info
            type: McpTool
            description: 取得檔案元資料 (無需核准)。
          - name: write_file
            type: McpTool
            description: 建立或更新檔案 (⚠️ 需要核准)。
          - name: write_text_file
            type: McpTool
            description: 寫入文字檔案 (⚠️ 需要核准)。
          - name: create_directory
            type: McpTool
            description: 建立新目錄 (⚠️ 需要核准)。
          - name: move_file
            type: McpTool
            description: 移動或重新命名檔案 (⚠️ 需要核准)。
    generate_content_config:
      temperature: 0.2
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - mcp
      - filesystem
      - hitl
      - security
      - callbacks
      - approval-workflow
  - name: Model Selector Agent
    description: 用於選擇和比較 AI 模型的專家 agent，可根據使用場景推薦最佳模型。
    code_ref: workspace/python/agents/model-selector
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: recommend_model_for_use_case
        type: FunctionTool
        description: 根據使用場景描述推薦模型。
      - name: get_model_info
        type: FunctionTool
        description: 獲取特定模型的詳細資訊。
    server-port: 8000
    tags:
      - model-selection
      - benchmark
      - comparison
      - recommendation
  - name: Multi-LLM Agent
    description: 支援 OpenAI, Claude, Ollama 等多種模型的 Multi-LLM agent，透過 LiteLLM 實現。此 agent 可以針對不同任務使用不同的 LLM 供應商。
    code_ref: workspace/python/agents/multi-llm-agent
    type: Agent
    model:
      - openai/gpt-4o-mini
      - 'anthropic/claude-3-7-sonnet-20250219'
      - 'ollama_chat/granite4:latest'
    tools:
      - name: calculate_square
        type: FunctionTool
        description: 計算一個數字的平方。
      - name: get_weather
        type: FunctionTool
        description: 取得指定城市目前的天氣 (模擬實作)。
      - name: analyze_sentiment
        type: FunctionTool
        description: 分析文字的情緒 (模擬實作)。
    server-port: 8000
    tags:
      - multi-llm
      - litellm
      - openai
      - claude
      - ollama
      - function-calling
      - model
  - name: Observability Agent
    description: 具備全面事件監控、指標收集與詳細報告功能的客戶服務代理程式。
    code_ref: workspace/python/agents/observability-agent
    type: Agent
    models:
      - gemini-2.0-flash-exp
    tools:
      - name: check_order_status
        type: FunctionTool
        description: 檢查訂單狀態。
      - name: process_refund
        type: FunctionTool
        description: 處理退款請求，金額超過 100 時上報。
      - name: check_inventory
        type: FunctionTool
        description: 檢查產品庫存。
    generate_content_config:
      temperature: 0.5
      max_output_tokens: 1024
    server-port: 8000
    tags:
      - observability
      - events
      - monitoring
      - customer-service
      - metrics
      - logging
      - reporting
  - name: Observability Plugins Agent
    description: 具有全面可觀測性的生產助理，包括指標收集、警報和效能分析，用於企業監控。
    code_ref: workspace/python/agents/observability-plugins-agent
    type: Agent
    models:
      - gemini-2.5-flash
    generate_content_config:
      temperature: 0.5
      max_output_tokens: 1024
    server-port: 8000
    plugins:
      - name: metrics_collector_plugin
        type: BasePlugin
        description: 用於收集請求指標的外掛程式。
      - name: alerting_plugin
        type: BasePlugin
        description: 用於異常警報的外掛程式。
      - name: performance_profiler_plugin
        type: BasePlugin
        description: 用於詳細效能分析的外掛程式。
    tags:
      - observability
      - monitoring
      - plugins
      - metrics
      - alerting
      - profiling
  - name: Pack ADK A2A Agent
    description: 一個可以提供有關天氣和時間資訊的代理程式。
    code_ref: workspace/python/agents/pack-adk-a2a-agent
    type: Agent
    models:
      - gemini-3-pro-preview
    tools:
      - name: get_weather
        type: FunctionTool
        description: 模擬網路搜尋。使用它來獲取天氣資訊。
      - name: get_current_time
        type: FunctionTool
        description: 模擬獲取城市的當前時間。
    protocol: a2a
    server-port: 8000
    tags:
      - a2a
      - agent-starter-pack
      - fastapi
      - uvicorn
      - terraform
      - storage
      - monitoring
      - agent-card
      - telemetry
      - logger
  - name: Pause Resume Agent
    description: 展示 ADK 1.16.0 中暫停與恢復調用 (Pause and Resume Invocations) 的 Agent。
    code_ref: workspace/python/agents/pause-resume-agent
    type: App
    models:
      - gemini-2.0-flash
    tools:
      - name: process_data_chunk
        type: FunctionTool
        description: 模擬處理資料塊，代表一個能從暫停/恢復中受益的長期執行操作。
      - name: validate_checkpoint
        type: FunctionTool
        description: 驗證恢復時的檢查點完整性，展示恢復前的狀態驗證。
      - name: get_resumption_hint
        type: FunctionTool
        description: 分析上下文並建議最佳恢復點。
    server-port: 8000
    resumability_config:
      - is_resumable
    tags:
      - pause-resume
      - checkpoint
      - long-running-workflow
      - resumability-config
  - name: Personal Tutor
    description: 個人化學習導師，展示多層次狀態與記憶管理，追蹤使用者進度、偏好與學習歷史。
    code_ref: workspace/python/agents/personal-tutor
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: set_user_preferences
        type: FunctionTool
        description: '設定使用者學習偏好（語言、難度），使用 user: 前綴進行永久儲存。'
      - name: record_topic_completion
        type: FunctionTool
        description: 紀錄使用者完成的學習主題與測驗分數，更新永久狀態的已完成主題列表與分數映射。
      - name: get_user_progress
        type: FunctionTool
        description: 取得使用者學習進度摘要，包含語言偏好、難度層級、已完成主題數量與平均測驗分數。
      - name: start_learning_session
        type: FunctionTool
        description: 啟動新的主題學習工作階段，設定工作階段層級狀態（無前綴），包含當前主題與開始時間。
      - name: calculate_quiz_grade
        type: FunctionTool
        description: '計算測驗成績，使用 temp: 前綴儲存中間計算結果（單次呼叫作用域），回傳分數與等級評定。'
      - name: search_past_lessons
        type: FunctionTool
        description: 搜尋過往學習紀錄，模擬記憶服務功能，在已完成主題中尋找與查詢相關的內容。
    server-port: 8000
    output_key: last_tutor_response
    tags:
      - state-management
      - memory
      - user-preferences
      - progress-tracking
      - session-management
      - learning-analytics
      - tutorial08
  - name: Policy Navigator
    description: 企業合規與政策導航器，使用 Google Gemini File Search API 實作原生 RAG 進行政策管理、搜尋與分析。
    code_ref: workspace/python/agents/policy-navigator
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: upload_policy_documents
        type: FunctionTool
        description: 以 upsert 語意上傳政策文件到 File Search Store。如果具有相同名稱的文件已存在，將被取代。
      - name: search_policies
        type: FunctionTool
        description: 使用 File Search 對政策進行語意搜尋，支援 metadata 過濾。
      - name: filter_policies_by_metadata
        type: FunctionTool
        description: 依 metadata 屬性（部門、政策類型、敏感度、管轄區）過濾政策。
      - name: compare_policies
        type: FunctionTool
        description: 跨部門比較政策，識別不一致或衝突之處。
      - name: check_compliance_risk
        type: FunctionTool
        description: 評估與政策相關的合規風險並提供建議。
      - name: extract_policy_requirements
        type: FunctionTool
        description: 從政策中擷取特定需求與關鍵資訊。
      - name: generate_policy_summary
        type: FunctionTool
        description: 建立簡潔的政策摘要與執行報告。
      - name: create_audit_trail
        type: FunctionTool
        description: 建立稽核追蹤項目，追蹤所有政策存取與決策。
    server-port: 8000
    output_key: policy_navigator_result
    tags:
      - file-search
      - rag
      - compliance
      - multi-agent
      - metadata
      - audit-trail
      - store
      - coordinator
    sub_agents:
      - name: Document Manager
        description: 管理政策文件上傳、組織與 metadata 設定。
        type: Agent
        invoke: prompting
        models:
          - gemini-2.5-flash
        tools:
          - name: upload_policy_documents
            type: FunctionTool
            description: 將政策文件上傳到 File Search stores 並設定 metadata。
        server-port: null
        output_key: document_manager_result
        tags:
          - document-management
          - file-upload
          - metadata
      - name: Search Specialist
        description: 搜尋公司政策並檢索相關資訊，提供準確的政策資訊並附帶引用。
        type: Agent
        invoke: prompting
        models:
          - gemini-2.5-flash
        tools:
          - name: search_policies
            type: FunctionTool
            description: 對政策文件執行語意搜尋。
          - name: filter_policies_by_metadata
            type: FunctionTool
            description: 依部門、類型與日期過濾政策。
          - name: extract_policy_requirements
            type: FunctionTool
            description: 從政策中擷取特定需求。
        server-port: null
        output_key: search_specialist_result
        tags:
          - search
          - retrieval
          - semantic-search
      - name: Compliance Advisor
        description: 評估合規風險並提供政策指導，識別不一致或衝突之處。
        type: Agent
        invoke: prompting
        models:
          - gemini-2.5-flash
        tools:
          - name: check_compliance_risk
            type: FunctionTool
            description: 評估與政策相關的合規風險。
          - name: compare_policies
            type: FunctionTool
            description: 跨部門比較政策，識別不一致之處。
        output_key: compliance_advisor_result
        server-port: null
        tags:
          - compliance
          - risk-assessment
          - policy-analysis
      - name: Report Generator
        description: 產生政策摘要、報告與稽核追蹤，為利益相關者格式化政策資訊。
        type: Agent
        invoke: prompting
        models:
          - gemini-2.5-flash
        tools:
          - name: generate_policy_summary
            type: FunctionTool
            description: 建立簡潔的政策摘要。
          - name: create_audit_trail
            type: FunctionTool
            description: 建立稽核追蹤項目。
        output_key: report_generator_result
        server-port: null
        tags:
          - reporting
          - summary
          - audit
  - name: Production Agent
    description: 生產環境部署專家，為 ADK 代理提供部署策略、最佳實踐和基礎設施模式的指導。
    code_ref: workspace/python/agents/production-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: check_deployment_status
        type: FunctionTool
        description: 檢查部署狀態與健康狀況，返回包含部署狀態資訊的字典。
      - name: get_deployment_options
        type: FunctionTool
        description: 取得可用的部署選項，包括本地 API 伺服器、Cloud Run、Agent Engine 和 GKE 的詳細資訊。
      - name: get_best_practices
        type: FunctionTool
        description: 取得生產環境部署最佳實踐，涵蓋安全性、監控、可擴展性和可靠性方面的建議。
    generate_content_config:
      temperature: 0.5
      max_output_tokens: 2048
    server-port: 8000
    tags:
      - deployment
      - production
      - fastapi
      - cloud-run
      - gke
      - agent-engine
      - monitoring
      - security
      - uvicorn
      - middleware
      - health-checks
  - name: Pub/Sub Document Processor
    description: 事件驅動的文件路由協調者，透過 Pub/Sub 將上傳文件分發給專門分析代理並回傳結構化 JSON。
    code_ref: workspace/python/agents/pubsub-agent
    type: LlmAgent
    models:
      - gemini-2.5-flash
    tools:
      - name: financial_analyzer
        type: AgentTool
        description: 分析財務文件，提取財務指標、財政期間與建議的結構化輸出。
      - name: technical_analyzer
        type: AgentTool
        description: 分析技術文件與架構，回傳涉及技術元件與改進建議的 JSON。
      - name: sales_analyzer
        type: AgentTool
        description: 分析銷售交易與管道，提供交易狀態與銷售建議。
      - name: marketing_analyzer
        type: AgentTool
        description: 分析行銷活動與指標，整理參與率、轉換率與最佳化建議。

    server-port: 8000
    tags:
      - pubsub
      - topics
      - gcp
      - dlq
      - event-driven
      - document-routing
      - multi-agent
      - structured-output
    sub_agents:
      - name: Financial Analyzer
        description: 對財務報告進行結構化解析，擷取財務指標與財政期間。
        type: LlmAgent
        models:
          - gemini-2.5-flash
        tags:
          - finance
          - structured-output
        output_schema: FinancialAnalysisOutput
      - name: Technical Analyzer
        description: 解析技術文件，列出技術、元件與改進建議。
        type: LlmAgent
        models:
          - gemini-2.5-flash
        tags:
          - technical
          - architecture
          - structured-output
        output_schema: TechnicalAnalysisOutput
      - name: Sales Analyzer
        description: 解析銷售文件，萃取交易、管道價值與銷售建議。
        type: LlmAgent
        models:
          - gemini-2.5-flash
        tags:
          - sales
          - pipeline
          - structured-output
        output_schema: SalesAnalysisOutput
      - name: Marketing Analyzer
        description: 解析行銷文件，彙整活動、參與度與最佳化建議。
        type: LlmAgent
        models:
          - gemini-2.5-flash
        tags:
          - marketing
          - campaign
          - structured-output
        output_key: MarketingAnalysisOutput
  - name: Software Bug Assistant
    description: 一位熟練的軟體問題分類和除錯專家，專為咖啡機公司 QuantumRoast 提供票務管理服務。整合多種工具進行票務搜尋、建立、更新與網路查詢。
    code_ref: workspace/python/agents/software-bug-assistant
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: get_current_date
        type: FunctionTool
        description: 取得當前日期(YYYY-MM-DD格式)，用於計算日期範圍查詢。
      - name: search_agent
        type: AgentTool
        description: 使用Google Search進行網路搜尋，查詢軟體社群中的已知問題(CVE、廣泛問題等)。
      - name: langchain_tool
        type: LangchainTool
        description: 在Stack Exchange(StackOverflow)上搜尋使用者過去的查詢與解決方案。
      - name: search-tickets
        type: ToolboxCoreClientTool
        description: 透過向量搜尋找出類似或重複的 ticket (限制 3 筆紀錄)。
      - name: update-ticket-status
        type: ToolboxCoreClientTool
        description: 更新 ticket狀態(開放、進行中、已關閉、已解決)。
      - name: update-ticket-priority
        type: ToolboxCoreClientTool
        description: 更新 ticket優先級(P0-關鍵、P1-高、P2-中等、P3-低)。
      - name: create-new-ticket
        type: ToolboxCoreClientTool
        description: 建立新的 ticket/問題。
      - name: get-ticket-by-id
        type: ToolboxCoreClientTool
        description: 透過ID檢索 ticket。
      - name: get-tickets-by-date-range
        type: ToolboxCoreClientTool
        description: 檢索特定日期範圍內建立或更新的 ticket。
      - name: get-tickets-by-assignee
        type: ToolboxCoreClientTool
        description: 檢索具有特定受託人的 ticket。
      - name: get-tickets-by-status
        type: ToolboxCoreClientTool
        description: 檢索具有特定狀態的 ticket。
      - name: get-tickets-by-priority
        type: ToolboxCoreClientTool
        description: 檢索具有特定優先級的 ticket。
      - name: github_search
        type: MCPTool
        description: 透過MCP工具在GitHub上搜尋儲存庫、問題與PR，支援search_repositories、search_issues、list_issues、get_issue、list_pull_requests、get_pull_request等操作。
      - name: mcp_tools
        type: MCPToolset
        transports: streamable
        description: 提供 GitHub Copilot MCP 各項服務與任務工具。
        tools:
          refs: 'https://github.com/github/github-mcp-server'
    server-port: 8000
    tags:
      - bug-tracking
      - ticket-management
      - toolbox
      - mcp
      - langchain
      - vector-search
      - sql-database
      - github-mcp
      - multi-tools
      - postgres
    sub_agents:
      - name: search_agent
        description: 使用Google Search的專家代理，負責網路搜尋任務。
        type: AgentTool
        models:
          - gemini-2.5-flash
        tools:
          - name: google_search
            type: GoogleSearchAgentTool
            description: Google搜尋工具。
        tags:
          - search
          - google
  - name: Strategic Problem Solver (BuiltInPlanner)
    description: 使用 BuiltInPlanner 進行透明思考的策略商業顧問，涵蓋市場分析、ROI 計算與風險評估並輸出策略報告。
    code_ref: workspace/python/agents/strategic-solver
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: analyze_market
        type: FunctionTool
        description: 分析指定產業與地區的市場狀況與趨勢。
      - name: calculate_roi
        type: FunctionTool
        description: 進行投資複利與 ROI 計算，提供年度分解。
      - name: assess_risk
        type: FunctionTool
        description: 依因素評估風險分數、等級與緩解優先度。
      - name: save_strategy_report
        type: FunctionTool
        description: 生成並保存策略計畫的 Markdown 報告。
    generate_content_config:
      temperature: 0.3
      max_output_tokens: 3000
    server-port: 8000
    output_key: builtin_strategy_result
    tags:
      - strategy
      - business-analysis
      - builtin-planner
      - market
      - roi
      - risk
  - name: Strategic Problem Solver (PlanReActPlanner)
    description: 使用 PlanReActPlanner 以「計劃→推理→行動→觀察→重規劃」結構進行策略分析與建議。
    code_ref: workspace/python/agents/strategic-solver
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: analyze_market
        type: FunctionTool
        description: 分析指定產業與地區的市場狀況與趨勢。
      - name: calculate_roi
        type: FunctionTool
        description: 進行投資複利與 ROI 計算，提供年度分解。
      - name: assess_risk
        type: FunctionTool
        description: 依因素評估風險分數、等級與緩解優先度。
      - name: save_strategy_report
        type: FunctionTool
        description: 生成並保存策略計畫的 Markdown 報告。
    generate_content_config:
      temperature: 0.4
      max_output_tokens: 3000
    server-port: 8000
    output_key: plan_react_strategy_result
    tags:
      - strategy
      - business-analysis
      - plan-react-planner
      - structured-reasoning
      - market
      - roi
      - risk
  - name: Strategic Problem Solver (Custom StrategicPlanner)
    description: 使用自訂 StrategicPlanner 的特定領域工作流程（ANALYSIS／EVALUATION／STRATEGY／VALIDATION）產生可執行的策略建議。
    code_ref: workspace/python/agents/strategic-solver
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: analyze_market
        type: FunctionTool
        description: 分析指定產業與地區的市場狀況與趨勢。
      - name: calculate_roi
        type: FunctionTool
        description: 進行投資複利與 ROI 計算，提供年度分解。
      - name: assess_risk
        type: FunctionTool
        description: 依因素評估風險分數、等級與緩解優先度。
      - name: save_strategy_report
        type: FunctionTool
        description: 生成並保存策略計畫的 Markdown 報告。
    generate_content_config:
      temperature: 0.3
      max_output_tokens: 3000
    server-port: 8000
    output_key: strategic_planner_result
    tags:
      - strategy
      - business-analysis
      - custom-planner
      - domain-workflow
      - market
      - roi
      - risk
      - base-planner
  - name: Streaming Agent
    description: 一個示範 Server-Sent Events (SSE) 串流回應的代理人，透過即時、漸進式的輸出改善使用者體驗。
    code_ref: workspace/python/agents/streaming-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: format_streaming_info
        type: FunctionTool
        description: 提供有關串流功能的資訊，包括支援的串流模式、效能優勢與使用情境。
      - name: analyze_streaming_performance
        type: FunctionTool
        description: 分析串流效能特性，包括預估區塊數、時間估計與記憶體效率。
    generate_content_config:
      temperature: 0.7
      max_output_tokens: 2048
      top_p: 0.8
      top_k: 40
    server-port: 8000
    runner:
      run_config:
        streaming_mode: sse
        max_llm_calls: 50
    tags:
      - sse
      - streaming
      - real-time
      - async-iteration
      - gemini-2.0-flash
      - streaming_mode,
      - fastapi,
      - html,
      - uvicorn,
      - chunks
  - name: Support Agent
    description: 客戶支援代理 - 可測試的模式示範。提供知識庫搜尋、建立支援工單、查詢工單狀態等功能，展示清晰的工具使用、結構化回應與確定性行為。
    code_ref: workspace/python/agents/support-agent
    type: Agent
    models:
      - gemini-2.0-flash-exp
    tools:
      - name: search_knowledge_base
        type: FunctionTool
        description: 在知識庫中搜尋常見客戶問題的資訊。使用記憶體內知識庫提供確定性結果，支援不區分大小寫的關鍵字比對。涵蓋密碼重設、退款政策、運送、帳戶管理、帳單和技術支援等主題。
      - name: create_ticket
        type: FunctionTool
        description: '為客戶問題建立新的支援工單。支援四種優先級別（low, normal, high, urgent），自動生成唯一工單 ID (TICK-XXXXXXXX 格式)，並根據優先級設定預估回應時間（urgent: 4小時, high: 24小時, normal: 2工作天, low: 5工作天）。'
      - name: check_ticket_status
        type: FunctionTool
        description: 查詢現有支援工單的狀態。使用工單 ID 檢索工單詳細資訊，包括問題描述、優先級別、當前狀態、建立時間和預估回應時間。
    output_key: support_response
    tags:
      - customer-support
      - evaluation
      - testable-patterns
      - knowledge-base
      - ticketing
      - deterministic
      - structured-response
  - name: Support Bot
    description: Slack Socket Mode 的團隊支援助理，使用內建知識庫回答公司政策與 IT 問題，並可建立支援工單示範 ADK 工具整合。
    code_ref: workspace/python/agents/support-bot
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: search_knowledge_base
        type: FunctionTool
        description: 以加權關鍵字比對搜尋內建知識庫，回傳最佳文章或建議查詢提示。
      - name: create_support_ticket
        type: FunctionTool
        description: 驗證優先順序後建立支援工單，回傳工單 ID 與摘要供後續追蹤。
    server-port: 8000
    tags:
      - slack
      - support
      - knowledge-base
      - ticketing
      - socket-mode
      - adk
  - name: Third-Party Integration Agent
    description: 綜合研究與檔案分析代理，整合 LangChain Wikipedia/DuckDuckGo 與 CrewAI 檔案工具，無需 API 金鑰。
    code_ref: workspace/python/agents/third-party-agent
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: wikipedia_search
        type: LangchainTool
        description: 使用 LangChain 的 WikipediaQueryRun 查詢百科知識。
      - name: web_search
        type: LangchainTool
        description: 使用 LangChain 的 DuckDuckGoSearchRun 搜尋最新資訊。
      - name: directory_read
        type: DirectoryReadTool
        description: 使用 CrewAI DirectoryReadTool 讀取目錄內容。
      - name: file_read
        type: FileReadTool
        description: 使用 CrewAI FileReadTool 讀取檔案內容。
    server-port: 8000
    output_key: research_response
    tags:
      - third-party
      - langchain
      - crewai
      - wikipedia
      - duckduckgo
      - filesystem
      - research
      - analysis
  - name: Tool Use Evaluator
    description: 用於展示工具使用品質（Tool Use Quality）評估的代理，涵蓋正確工具排序、依賴性與錯誤處理。
    code_ref: workspace/python/agents/tool-use-evaluator
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: analyze_data
        type: FunctionTool
        description: 分析指定資料集，回傳基本統計與欄位型態。
      - name: extract_features
        type: FunctionTool
        description: 從分析結果中提取特徵（mean、median、std_dev、correlation）。
      - name: validate_quality
        type: FunctionTool
        description: 驗證特徵品質並提供分數與通過狀態。
      - name: apply_model
        type: FunctionTool
        description: 將指定 ML 模型套用於特徵並回傳預測與準確度。
    server-port: 8000
    output_key: analysis_result
    tags:
      - tool-use-quality
      - evaluation
      - data-analysis
      - function-tools
      - tools-ordering
  - name: Travel Planner
    description: 平行搜尋航班、飯店與活動，並聚合成完整行程表的教學範例。
    code_ref: workspace/python/agents/travel-planner
    type: SequentialAgent
    models: []
    server-port: 8000
    tags:
      - travel
      - parallel
      - sequential
      - fan-out
      - gather
      - itinerary
      - parallel-search
    sub_agents:
      - name: ParallelSearch
        description: 平行搜尋航班、飯店與活動，將結果寫入 state。
        type: ParallelAgent
        tags:
          - parallel-search
          - fan-out
        sub_agents:
          - name: flight_finder
            description: 搜尋可用航班並提供時間、價格與航空公司選項。
            type: Agent
            models:
              - gemini-2.0-flash
            output_key: flight_options
            tags:
              - flights
              - search
          - name: hotel_finder
            description: 尋找合適的飯店，包含位置、評等、價格與設施重點。
            type: Agent
            models:
              - gemini-2.0-flash
            output_key: hotel_options
            tags:
              - hotels
              - search
          - name: activity_finder
            description: 推薦目的地活動與景點，提供時間與費用估計。
            type: Agent
            models:
              - gemini-2.0-flash
            output_key: activity_options
            tags:
              - activities
              - search
      - name: itinerary_builder
        description: 從 state 合併航班、飯店與活動選項，生成格式化行程表與建議。
        type: Agent
        models:
          - gemini-2.0-flash
        output_key: final_itinerary
        tags:
          - itinerary
          - planner
          - gather
  - name: UI Integration Quickstart Agent
    description: 您是由 Google ADK 驅動的樂於助人的人工智慧助理。整合 AG-UI 協定與 CopilotKit 相容中介軟體，提供 React 前端整合 fastapi 後端應用的完整服務。
    code_ref: workspace/python/agents/ui-integration
    type: ADKAgent
    models:
      - gemini-2.0-flash-exp
    server-port: 8000
    tags:
      - ui-integration
      - ag-ui
      - copilotkit
      - fastapi
      - uvicorn
      - reactjs
      - middleware
      - frontend
  - name: Vision Catalog Coordinator
    description: 具有多模態能力的視覺化產品目錄協調器，可以分析產品圖片、生成合成產品模型、比較多張圖片並建立專業的產品目錄條目。
    code_ref: workspace/python/agents/vision-catalog-agent
    type: Agent
    models:
      - gemini-2.0-flash-exp
      - gemini-2.5-flash-image
    tools:
      - name: list_sample_images
        type: FunctionTool
        description: 列出 _sample_images 目錄中可用的範例產品圖片，供使用者選擇和分析。
      - name: generate_product_mockup
        type: FunctionTool
        description: 使用 Gemini 2.5 Flash Image 生成合成產品圖片，適合原型設計、測試或生成產品變化版本。
      - name: analyze_uploaded_image
        type: FunctionTool
        description: 分析直接在查詢中上傳的圖片，提供結構化分析框架和指引。
      - name: analyze_product_image
        type: FunctionTool
        description: 分析產品圖片並自動生成詳細的視覺分析與專業目錄條目。
      - name: compare_product_images
        type: FunctionTool
        description: 比較多張產品圖片，識別異同點並提供結構化的比較分析。
    generate_content_config:
      temperature: 0.7
      max_output_tokens: 2048
    tags:
      - vision
      - multimodal
      - image-analysis
      - product-catalog
      - e-commerce
    sub_agents:
      - name: vision_analyzer
        description: 分析產品圖片並提取視覺資訊，包括產品識別、視覺特徵、品質指標。
        type: Agent
        models:
          - gemini-2.0-flash-exp
        generate_content_config:
          temperature: 0.3
          max_output_tokens: 1024
        tags:
          - vision
          - image-analysis
          - product-identification
      - name: catalog_generator
        description: 根據視覺分析結果生成專業、可用於行銷的產品描述和目錄條目。
        type: Agent
        models:
          - gemini-2.0-flash-exp
        tools:
          - name: generate_catalog_entry
            type: FunctionTool
            description: 生成並儲存可用於行銷的目錄條目為 artifact。
        generate_content_config:
          temperature: 0.6
          max_output_tokens: 1536
        tags:
          - catalog
          - content-creation
          - marketing
  - name: Voice Assistant
    description: 支援 Live API 的即時語音助理，可進行雙向串流對話、麥克風錄音和喇叭播放。
    code_ref: workspace/python/agents/voice-assistant
    type: App
    models:
      - gemini-2.0-flash-live-001
      - gemini-2.5-flash
    generate_content_config:
      temperature: 0.8
      max_output_tokens: 150
    runner:
      run_config:
        streaming_mode:
        speech_config:
          voice_config: voice_config_default
        max_llm_calls: 20
    tools:
      - name: record_audio
        description: 從麥克風錄製指定時長的音訊
      - name: play_audio
        description: 透過喇叭播放音訊 bytes
      - name: send_text
        description: 傳送文字訊息並取得 Agent 回應
      - name: send_audio
        description: 傳送音訊並取得文字和音訊回應
      - name: conversation_turn
        description: 執行完整的音訊對話回合 (錄音 → 傳送 → 接收 → 播放)
    tags:
      - live-api
      - voice
      - real-time-streaming
      - audio
      - multimodal
      - conversational-ai
  - name: YouTube Shorts Agent
    description: 一個協調代理，整合腳本編寫、視覺創作和格式化子代理，自動生成 YouTube 短視頻內容。
    code_ref: workspace/python/agents/youtube-shorts-assistant
    type: Agent
    models:
      - gemini-2.0-flash-001
    tools:
      - name: scriptwriter_agent
        type: AgentTool
        description: 根據主題和要求生成簡潔的短視頻腳本 (15-50秒)。
      - name: visualizer_agent
        type: AgentTool
        description: 為腳本段落創建動態的垂直 (9:16) 視覺概念。
      - name: formatter_agent
        type: AgentTool
        description: 使用 Markdown 整合和格式化腳本與視覺概念。
    server-port: 8000
    tags:
      - youtube-shorts
      - content-creation
      - multi-agent
      - gemini
      - adk
    sub_agents:
      - name: Scriptwriter Agent
        description: 負責編寫引人注目的短視頻腳本。
        type: LlmAgent
        models:
          - gemini-2.0-flash-001
        tools:
          - name: google_search
            type: GoogleSearchAgentTool
            description: 搜尋資訊以支持腳本創作。
        tags:
          - scriptwriting
          - content-creation
          - adk
      - name: Visualizer Agent
        description: 負責創建與腳本對應的視覺概念。
        type: LlmAgent
        models:
          - gemini-2.0-flash-001
        tags:
          - visual-design
          - content-creation
          - adk
      - name: Formatter Agent
        description: 負責整合腳本和視覺概念，並使用 Markdown 進行格式化。
        type: LlmAgent
        models:
          - gemini-2.0-flash-001
        tags:
          - formatting
          - content-creation
          - adk
  - name: RAG Knowledge Management Agent
    description: 採用 RAG (檢索增強生成) 架構的知識管理代理，整合 Vertex AI Search、Vertex AI Rank 與 Gemini 模型，提供基於文件檢索的智能問答服務。
    code_ref: workspace/python/agents/rag-km-agents
    type: App
    models:
      - name: gemini-3-flash-preview
        retry_options:
          attempts: 3
    tools:
      - name: retrieve_docs
        type: FunctionTool
        description: 根據使用者查詢從 Vertex AI Search 資料儲存庫檢索相關文件，並透過 Vertex AI Rank 進行重新排序，以提供更準確的上下文資訊。
    tags:
      - rag
      - knowledge-management
      - vertex-ai-search
      - vertex-ai-rank
      - fastapi
      - cloud-run
      - terraform
      - observability
      - embedding-model
      - langchain
      - uvicorn
      - middleware
  - name: Live Interact Agent
    description: 使用 ADK 和 Gemini Live API 的即時多模態代理，透過 WebSocket 雙向串流支援語音與文字互動並內建前端介面。
    code_ref: workspace/python/agents/live-interact-agent
    type: App
    models:
      - gemini-live-2.5-flash-native-audio
    tools:
      - name: get_weather
        type: FunctionTool
        description: 模擬網路搜尋以回傳指定城市的天氣資訊。
    server-port: 8000
    tags:
      - live-api
      - websocket
      - fastapi
      - frontend
      - telemetry
      - gcs
      - cloud-run
      - gemini-live
  - name: Brand Search Optimization
    description: |
      此代理旨在透過生成關鍵字、進行網站搜尋及分析結果，協助零售網站強化其商品資料，以改善搜尋結果不佳的問題。
    code_ref: workspace/python/agents/brand-search-optimization/
    type: Agent
    models:
      - gemini-2.5-flash
    server-port: 8000
    tags:
      - retail
      - multi-agent
      - web-crawling
      - bigquery
      - router-agent
    sub_agents:
      - name: keyword_finding_agent
        description: 根據品牌名稱尋找相關的搜尋關鍵字 (bigquery)。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: get_product_details_for_brand
            type: FunctionTool
            description: 用於在 BigQuery 中執行 SQL 查詢的工具。
      - name: search_results_agent
        description: 使用關鍵字在網站上執行搜尋並抓取結果。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: go_to_url
            type: FunctionTool
            description: 瀏覽指定的 URL 並返回確認訊息。
          - name: take_screenshot
            type: FunctionTool
            description: 擷取當前畫面的螢幕截圖，並呼叫 'load_artifacts_tool' 來載入圖片。
          - name: find_element_with_text
            type: FunctionTool
            description: 在頁面上尋找包含指定文字的元素。
          - name: click_element_with_text
            type: FunctionTool
            description: 在頁面上點擊包含指定文字的元素。
          - name: enter_text_into_element
            type: FunctionTool
            description: 在具有指定 ID 的元素中輸入文字。
          - name: scroll_down_screen
            type: FunctionTool
            description: 將螢幕向下捲動一個固定的距離。
          - name: get_page_source
            type: FunctionTool
            description: 返回當前頁面的 HTML 原始碼。
          - name: load_artifacts_tool
            type: FunctionTool
            description: 讀取並載入指定路徑的 artifact。
          - name: analyze_webpage_and_determine_action
            type: FunctionTool
            description: 分析網頁內容並決定下一個動作（捲動、點擊等）。
      - name: comparison_root_agent
        description: 路由代理以生成和評論比較。
        type: Agent
        models:
          - gemini-2.5-flash
        sub_agents:
          - name: comparison_generator_agent
            description: 根生成產品標題之間的比較報告。
            type: Agent
            models:
              - gemini-2.5-flash
          - name: comparison_critic_agent
            description: 評論比較並提供有用的建議。
            type: Agent
            models:
              - gemini-2.5-flash
  - name: Pack Customer Service Agent
    description: |
      整合 Google Cloud 服務與大型語言模型 (LLM) 的進階客戶服務 AI 代理系統。
      透過 FastAPI 提供 API，並整合了分散式追蹤與結構化日誌，確保系統在生產環境中的穩定性與可維護性。
    code_ref: workspace/python/agents/pack-customer-service
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: send_call_companion_link
        type: FunctionTool
        description: 發送連結至使用者的電話號碼以啟動視訊會話。
      - name: approve_discount
        type: FunctionTool
        description: 批准使用者請求的固定金額或百分比折扣。
      - name: sync_ask_for_approval
        type: FunctionTool
        description: 向經理請求折扣批准。
      - name: update_salesforce_crm
        type: FunctionTool
        description: 使用客戶詳情更新 Salesforce CRM。
      - name: access_cart_information
        type: FunctionTool
        description: 獲取購物車資訊。
      - name: modify_cart
        type: FunctionTool
        description: 透過添加和/或刪除商品來修改使用者的購物車。
      - name: get_product_recommendations
        type: FunctionTool
        description: 根據植物類型提供產品建議。
      - name: check_product_availability
        type: FunctionTool
        description: 在指定商店（或自取）檢查產品庫存。
      - name: schedule_planting_service
        type: FunctionTool
        description: 預約種植服務。
      - name: get_available_planting_times
        type: FunctionTool
        description: 檢索給定日期的可用種植服務時段。
      - name: send_care_instructions
        type: FunctionTool
        description: 發送有關如何照顧特定植物類型的電子郵件或簡訊說明。
      - name: generate_qr_code
        type: FunctionTool
        description: 生成折扣的 QR Code。
    before_agent_callback:
      - name: before_agent
        type: BeforeAgentCallback
        description: 在會話開始時，將客戶的完整資料載入到會話狀態中。
    before_model_callback:
      - name: rate_limit_callback
        type: BeforeModelCallback
        description: 在 LLM 調用前，實作 RPM (每分鐘請求數) 限制。
    before_tool_callback:
      - name: before_tool
        type: BeforeToolCallback
        description: 在工具執行前，進行參數標準化、安全驗證和業務規則捷徑處理。
    after_tool_callback:
      - name: after_tool
        type: AfterToolCallback
        description: 在工具執行後，根據工具結果執行確定性的後續操作。
    server-port: 8000
    tags:
      - customer-service
      - fastapi
      - observability
      - gcs
      - otel
      - callbacks
      - pydantic
  - name: Policy as Code Agent
    description: |
      一個高效的代理，用於檢查中繼資料中的政策違規情況。
      它擁有一個版本控制的記憶體來儲存和擷取政策，使其更快、更一致。
      主要工作流程包含：
      1. 根據使用者選擇的 GCS 路徑或 Dataplex 查詢來決定政策來源。
      2. 在記憶體中尋找現有政策，若無則生成新政策並儲存。
      3. 執行政策並報告違規情況。
      4. 提供修復建議、合規計分卡、歷史分析等進階功能。
      5. 整合 MCP 工具以增強與 Dataplex 資源的互動。
    code_ref: workspace/python/agents/pack-policy-as-code/
    type: App
    models:
      - gemini-2.5-flash
    tools:
      - name: find_policy_in_memory
        type: FunctionTool
        description: 在記憶體中尋找相似的政策。
      - name: save_policy_to_memory
        type: FunctionTool
        description: 將新政策或更新後的政策儲存到記憶體中。
      - name: list_policy_versions
        type: FunctionTool
        description: 列出特定政策的所有版本。
      - name: get_policy_by_id
        type: FunctionTool
        description: 根據 ID 和版本號擷取特定政策。
      - name: prune_memory
        type: FunctionTool
        description: 從記憶體中移除舊的或未使用的政策。
      - name: rate_policy
        type: FunctionTool
        description: 讓使用者對政策的有效性進行評分。
      - name: generate_policy_code_from_gcs
        type: FunctionTool
        description: 從 GCS 檔案的結構描述生成政策程式碼。
      - name: run_policy_from_gcs
        type: FunctionTool
        description: 針對 GCS 中的元數據檔案執行政策。
      - name: generate_policy_code_from_dataplex
        type: FunctionTool
        description: 從 Dataplex 查詢結果生成政策程式碼。
      - name: run_policy_on_dataplex
        type: FunctionTool
        description: 針對 Dataplex 搜尋結果執行政策。
      - name: get_supported_examples
        type: FunctionTool
        description: 返回範例政策查詢的列表。
      - name: suggest_remediation
        type: FunctionTool
        description: 為發現的策略違規建議修復措施。
      - name: get_execution_history
        type: FunctionTool
        description: 查詢過去的政策執行歷史。
      - name: analyze_execution_history
        type: FunctionTool
        description: 對執行歷史進行深入分析。
      - name: generate_compliance_scorecard
        type: FunctionTool
        description: 針對資料集執行一組核心政策並計算合規性分數。
      - name: export_report
        type: FunctionTool
        description: 將違規報告匯出為 CSV 或 HTML 格式。
      - name: get_active_core_policies
        type: FunctionTool
        description: 獲取目前設定的核心政策。
      - name: save_core_policies
        type: FunctionTool
        description: 將當前的核心政策設定儲存為永久設定。
      - name: add_core_policy
        type: FunctionTool
        description: 將新政策新增至核心政策集。
      - name: remove_core_policy
        type: FunctionTool
        description: 從核心政策集中移除政策。
      - name: PreloadMemoryTool
        type: PreloadMemoryTool
        description: 預加載記憶體工具。
      - name: Dataplex MCP Toolset
        type: MCPToolset
        description: 提供與 Dataplex MCP 伺服器互動的工具集。
    after_agent_callback:
      - name: auto_save_session_to_memory_callback
        type: AfterAgentCallback
        description: 在代理執行後自動將會話儲存到記憶體中。
    server-port: 8000
    tags:
      - policy-as-code
      - gcs
      - dataplex
      - compliance
      - mcp
      - memory
      - fastapi
      - cloud-run
      - callbacks
  - name: Cache Analysis Assistant
    description: |
      本代理人設計用於測試 ADK 的 context caching（上下文快取）功能，並以超過 2048 tokens 的大型提示來滿足隱式與顯式快取需求。
    # 並以超過 2048 tokens 的大型提示來滿足隱式與顯式快取需求。
    code_ref: workspace/python/agents/cache-analysis
    type: App
    models:
      - gemini-2.0-flash-001
    tools:
      - name: analyze_data_patterns
        type: FunctionTool
        description: |
          分析資料模式並提供見解。此工具可進行全面性的資料分析，包括統計分析、趨勢識別、異常偵測、相關性分析與預測建模。
          支援多種資料格式（CSV、JSON、XML 及純文字資料結構）。
      - name: research_literature
        type: FunctionTool
        description: |
          針對指定主題進行學術與專業文獻研究。此工具可跨多個學術資料庫、專業期刊、會議論文與產業報告進行全面性文獻研究。
          能分析研究趨勢、找出關鍵作者與機構、萃取方法論並整合多來源發現。支援系統性回顧、統合分析、書目計量分析、引用網絡分析。
      - name: generate_test_scenarios
        type: FunctionTool
        description: |
          產生系統驗證用的全面性測試情境。此工具可為各類系統（軟體、AI 模型、分散式系統、硬體元件）產生詳細測試情境、測試案例與驗證流程。
          支援多種測試方法（單元、整合、效能、安全、使用者驗收等）。可產生正向/負向案例、邊界條件、壓力測試與失敗情境。
      - name: optimize_system_performance
        type: FunctionTool
        description: |
          分析系統效能並提供詳細的最佳化建議。執行全面性的系統效能分析，包括瓶頸識別、資源利用評估、擴展性規劃，
          並根據系統類型與限制提供具體的最佳化策略。
      - name: analyze_security_vulnerabilities
        type: FunctionTool
        description: |
          執行全面性的安全弱點分析與風險評估。此工具進行詳細的安全分析，包括弱點識別、威脅建模、合規性缺口分析，
          並根據風險等級與業務影響提供優先修正策略。
      - name: design_scalability_architecture
        type: FunctionTool
        description: |
          設計因應預期成長的全面性擴展性架構。此工具分析現有系統架構，設計可因應用戶、資料、流量與複雜度成長的擴展性解決方案，
          同時維持效能、可靠性與成本效益。
      - name: benchmark_performance
        type: FunctionTool
        description: |
          執行全面性的效能基準測試與分析。此工具針對多個維度進行詳細效能基準測試，包括回應時間、吞吐量、資源利用、擴展性極限，
          以及各種負載條件下的系統穩定性。支援合成與真實工作負載測試，並可調整參數與監控。
    context_cache_config:
      min_tokens: 4096
      ttl_seconds: 600
      cache_intervals: 3
    tags:
      - research
      - analysis
      - performance
      - security
      - testing
      - context-caching
      - benchmarking
      - optimization
  - name: Bingo Digital Pet
    description: |
      此代理程式展示了如何使用靜態指令 (Static Instruction) 進行上下文快取 (Context Caching)，
      並透過一個根據存儲在會話狀態 (Session State) 中的餵食時間而展現不同情緒的數位寵物來呈現。
    code_ref: workspace/python/agents/static-instruction
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: eat
        type: FunctionTool
        description: |
          餵食數位寵物 Bingo。在以下情況下使用此工具：
          - 使用者明確提到餵食寵物（例如：「餵 Bingo」、「給食物」、「這是零食」）
          - Bingo 非常飢餓或餓扁了，並直接要求食物

          此工具會在會話狀態中設置餵食時間戳記，用於追蹤 Bingo 的飢餓程度和情緒變化。
    static_instruction: true
    instruction:
      name: provide_dynamic_instruction
      description: 為數位寵物 Bingo 提供基於飢餓度的動態指令。
      type: Function
    tags:
      - digital-pet
      - static-instruction
      - context-caching
      - session-state
      - interactive
      - dynamic-instruction
  - name: Hello World App
    description: |
      此說明描述一個負責擲骰子、使用工具檢查質數，並遵循特定步驟回應的代理人角色。
    code_ref: workspace/python/agents/hello-world-app
    type: App
    models:
      - gemini-2.0-flash
    tools:
      - name: roll_die
        type: FunctionTool
        description: |
          擲骰子並回傳結果。此工具接受骰子面數作為參數，並將每次擲骰結果儲存至會話狀態中的 'rolls' 列表。
          使用者可以透過此工具擲不同面數的骰子（例如：6 面、8 面、20 面骰子）。
      - name: check_prime
        type: FunctionTool
        description: |
          檢查給定的數字列表是否為質數。此工具接受一個整數列表，並回傳哪些數字是質數。
          使用非同步處理來提高效能。
      - name: load_artifacts
        type: LoadArtifactsTool
        description: |
          載入之前儲存的 artifacts 檔案。此工具由 ADK 提供，可以載入會話中儲存的檔案。
    plugins:
      - name: CountInvocationPlugin
        type: BasePlugin
        description: |
          自定義插件，用於統計代理人與工具的調用次數。
          追蹤三種計數：agent_count（代理人運行次數）、tool_count（工具調用次數）、llm_request_count（LLM 請求次數）。
          在每次調用前輸出計數資訊，方便追蹤與除錯。
      - name: SaveFilesAsArtifactsPlugin
        type: SaveFilesAsArtifactsPlugin
        description: |
          自動將生成的檔案儲存為 artifacts。此插件由 ADK 提供，可以自動處理檔案儲存。
    events_compaction_config:
      compaction_interval: 2
      overlap_size: 1
    generate_content_config:
      safety_settings:
        - category: HARM_CATEGORY_DANGEROUS_CONTENT
          threshold: OFF
    tags:
      - hello-world
      - demo
      - event-compaction
      - plugins
      - session-state
      - artifacts
      - parallel-tools
      - safety-settings

  - name: Human Tool Confirmation Agent
    description: 協助員工進行報銷及請假申請的代理助理。
    code_ref: workspace/python/agents/human-tool-confirmation
    type: App
    models:
      - gemini-2.5-flash
    tools:
      - name: reimburse
        type: FunctionTool
        description: 根據金額為員工報銷使用工具。
        require_confirmation:
          name: confirmation_threshold
          type: Function
          description: 當報銷金額超過此閾值時，需員工確認後方可執行。
      - name: request_time_off
        type: FunctionTool
        description: 員工請假申請工具。
    resumability_config:
      is_resumable: true
    generate_content_config:
      temperature: 0.1
    tags:
      - human-confirmation
      - tool-confirmation
      - resumability
      - approval-workflow
      - employee-services
  - name: A2A Basic
    description: |
      一個基礎的 A2A (Agent-to-Agent) 範例，展示了一個根代理 (Root Agent) 如何協調兩個子代理 (Sub-agents) 來完成任務。
    code_ref: workspace/python/agents/a2a-basic
    type: Agent
    models:
      - gemini-2.0-flash
    tools:
      - name: example_tool
        type: ExampleTool
        description: 提供對話範例，引導模型理解與 `roll_agent` 和 `prime_agent` 的互動流程。
    server-port: 8000
    safety_settings:
      - category: HARM_CATEGORY_DANGEROUS_CONTENT
        threshold: OFF
    tags:
      - a2a
      - orchestrator
      - remote-a2a
      - sub-agents
    sub_agents:
      - name: roll_agent
        description: 處理擲不同面數骰子的請求。
        type: Agent
        tools:
          - name: roll_die
            type: FunctionTool
            description: 擲一個指定面數的骰子並返回結果。
      - name: prime_agent
        description: 處理檢查數字是否為質數的請求。
        type: RemoteA2aAgent
        protocol: a2a
        models:
          - gemini-2.0-flash
        tools:
          - name: check_prime
            type: FunctionTool
            description: 檢查給定的數字列表是否包含質數。
        server-port: 8001
        tags:
          - a2a-remote
          - math
          - prime-checking

  - name: Pack Deep Search Agent
    description: |
      一個先進的迭代式深度研究代理系統，能夠執行多輪研究、自我評估並產生引用完整的研究報告。
      系統透過互動式規劃、迭代優化循環、來源追蹤與自動引用轉換，實現高品質的研究產出。
    code_ref: workspace/python/agents/pack-deep-search
    type: App
    models:
      - gemini-3-pro-preview
    tools:
      - name: plan_generator
        type: AgentTool
        description: 產生或精煉現有的 5 行行動導向研究計劃，僅使用最少搜尋來澄清主題。
        tools:
          name: google_search
          type: GoogleSearchTool
          description: 對每個 RESEARCH 目標產生 4-5 個具針對性的查詢並執行搜尋。
    server-port: 8000
    tags:
      - deep-research
      - iterative-refinement
      - auto-citation
      - quality-assurance
      - multi-agent
    output_key: research_plan
    sub_agents:
      - name: research_pipeline
        description: 執行預先核准的研究計劃，協調段落規劃、研究執行、迭代優化與報告撰寫。
        type: SequentialAgent
        models: []
        sub_agents:
          - name: section_planner
            description: 將研究計劃分解為結構化的 Markdown 報告章節大綱（4-6 個不重疊章節）。
            type: LlmAgent
            models:
              - gemini-3-pro-preview
            output_key: report_sections
          - name: section_researcher
            description: |
              執行關鍵的第一輪網頁研究。分兩階段處理：
              階段 1 (RESEARCH 任務)：系統性地執行搜尋並合成摘要。
              階段 2 (DELIVERABLE 任務)：基於收集的資訊產生具體產出物（表格、摘要等）。
            type: LlmAgent
            models:
              - gemini-3-pro-preview
            planner:
              type: BuiltInPlanner
              thinking_config:
                include_thoughts: true
            tools:
              - name: google_search
                type: GoogleSearchTool
                description: 對每個 RESEARCH 目標產生 4-5 個具針對性的查詢並執行搜尋。
            output_key: section_research_findings
            after_agent_callback:
              - name: collect_research_sources_callback
                type: AfterAgentCallback
                description: |
                  從 grounding 元資料提取來源資訊，分配短 ID (src-N)，
                  並收集每個來源支持的文字片段和信心分數。
          - name: iterative_refinement_loop
            description: 迭代優化循環，透過評估、檢查和額外搜尋來提升研究品質直到達標。
            type: LoopAgent
            max_iterations: 5
            sub_agents:
              - name: research_evaluator
                description: |
                  批判性地評估研究品質、深度和完整性。
                  評估覆蓋範圍、邏輯流動、來源可信度、分析深度和清晰度。
                  若發現差距則評定為 'fail' 並產生 5-7 個後續查詢，否則評定為 'pass'。
                type: LlmAgent
                models:
                  - gemini-3-pro-preview
                output_schema: Feedback
                output_key: research_evaluation
                disallow_transfer_to_parent: true
                disallow_transfer_to_peers: true
              - name: escalation_checker
                description: |
                  檢查研究評估結果。若評估為 'pass' 則發送升級事件以停止循環，
                  若為 'fail' 則發送空事件以繼續迭代。此為循環控制的關鍵組件。
                type: BaseAgent
              - name: enhanced_search_executor
                description: |
                  當評估失敗時執行後續搜尋並整合新發現。
                  檢視評估回饋，執行 follow_up_queries 中的每個查詢，
                  並將新發現與現有資訊結合以產生改進的研究結果。
                type: LlmAgent
                models:
                  - gemini-3-pro-preview
                planner:
                  type: BuiltInPlanner
                  thinking_config:
                    include_thoughts: true
                tools:
                  - name: google_search
                    type: GoogleSearchTool
                    description: 執行後續查詢以填補研究空白。
                output_key: section_research_findings
                after_agent_callback:
                  - name: collect_research_sources_callback
                    type: AfterAgentCallback
                    description: 收集新搜尋產生的來源資訊。
          - name: report_composer_with_citations
            description: |
              將研究數據和 Markdown 大綱轉換為最終的引用報告。
              使用特殊引用標籤系統 (<cite source="src-ID"/>)，
              透過 after_agent_callback 將標籤轉換為 Markdown 超連結。
            type: LlmAgent
            models:
              - gemini-3-pro-preview
            include_contents: none
            output_key: final_cited_report
            after_agent_callback:
              - name: citation_replacement_callback
                type: AfterAgentCallback
                description: |
                  將報告中的引用標籤 (<cite source="src-N"/>) 替換為 Markdown 格式的連結，
                  並修正標點符號周圍的多餘空格。最終產生帶有完整引用的報告。
  - name: GenMedia Agent
    description: |
      一個創意助理代理，透過生成式媒體工具協助使用者創建音訊、圖片和影片。
      整合了 Veo 影片生成、Chirp3 音訊生成、Imagen 圖片生成，以及 AVTool 音視訊合成工具。
      能夠根據使用者需求主動提供建議，並支援多語言翻譯功能。
    code_ref: workspace/python/agents/genmedia-agent
    type: LlmAgent
    models:
      - gemini-2.0-flash
    tools:
      - name: imagen
        type: MCPToolset
        description: 圖片生成工具，使用 Imagen 模型生成高品質圖片。
        transports: stdio
        refs: mcp-imagen-go
      - name: chirp3
        type: MCPToolset
        description: 音訊生成工具，使用 Chirp3 模型生成自然語音和音訊內容。
        transports: stdio
        refs: mcp-chirp3-go
      - name: veo
        type: MCPToolset
        description: 影片生成工具，使用 Veo 模型生成高品質影片內容。
        transports: stdio
        refs: mcp-veo-go
      - name: avtool
        type: MCPToolset
        description: 音視訊合成工具，用於合成和編輯音訊與影片媒體。
        transports: stdio
        refs: mcp-avtool-go
    tags:
      - generative-ai
      - media-generation
      - mcp
      - imagen
      - chirp3
      - veo
      - multimedia

  - name: Auto Insurance Agent
    description: 汽車保險代理人系統，採用多代理人架構處理客戶服務、理賠、道路救援、會員註冊與獎勵優惠查詢。
    code_ref: workspace/python/agents/pack-auto-insurance-agent/
    type: App
    models:
      - gemini-2.5-flash
    tools:
      - name: membership
        type: APIHubToolset
        description: 會員帳戶管理 API，用於註冊新會員和查詢會員資訊。
    sub_agents:
      - name: membership_agent
        description: 專門負責註冊新會員的代理人。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: membership
            type: APIHubToolset
            description: 會員帳戶管理 API，用於建立新的會員 ID。
      - name: roadside_agent
        description: 提供道路救援服務，包括拖吊、接電、燃料補充、更換輪胎等。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: roadsideAssistance
            type: APIHubToolset
            description: 道路救援 API，用於建立拖吊請求並提供預計到達時間。
      - name: claims_agent
        description: 處理汽車保險理賠案件，支援事故、冰雹損壞等各類理賠。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: claims
            type: APIHubToolset
            description: 理賠 API，用於開啟新的理賠案件並記錄相關細節。
      - name: rewards_agent
        description: 尋找附近商店、餐廳和劇院等地點的獎勵優惠。
        type: Agent
        models:
          - gemini-2.5-flash
        tools:
          - name: rewards
            type: APIHubToolset
            description: 獎勵 API，用於查詢會員可用的合作夥伴優惠。
    tags:
      - insurance
      - customer-service
      - multi-agent
      - api-hub
      - fastapi
      - claims
      - roadside-assistance
      - rewards

  - name: Short Movie Agents
    description: 根據使用者輸入，協調創作一個簡短的動畫營火故事，利用故事生成、分鏡腳本創作和影片生成的專業子代理。
    code_ref: workspace/python/agents/short-movie-agents
    type: Agent
    models:
      - gemini-2.5-flash
    server-port: 8000
    tags:
      - short-movie
      - content-creation
      - multi-agent
      - vertex-ai
      - imagen
      - veo
      - fastapi
    sub_agents:
      - name: story_agent
        description: 以親切且具吸引力的「童軍團長」風格提供答案與指導。所有回應皆以簡短、具啟發性的故事或軼事形式呈現。
        type: Agent
        models:
          - gemini-2.5-flash
        output_key: story
        tags:
          - story-generation
          - scout-leader
      - name: screenplay_agent
        description: 負責根據故事撰寫劇本的代理。
        type: Agent
        models:
          - gemini-2.5-flash
        output_key: screenplay
        tags:
          - screenplay-writing
      - name: storyboard_agent
        description: 負責根據劇本和故事建立分鏡腳本的代理。
        type: Agent
        models:
          - gemini-2.5-flash
        output_key: storyboard
        tools:
          - name: storyboard_generate
            type: FunctionTool
            description: 生成代表傳遞的提示詞的分鏡圖。
        tags:
          - storyboard-generation
          - imagen
      - name: video_agent
        description: 負責根據劇本和分鏡圖建立影片的代理。
        type: Agent
        models:
          - gemini-2.5-flash
        output_key: video
        tools:
          - name: video_generate
            type: FunctionTool
            description: 根據傳遞的提示詞和分鏡影像生成影片。
        tags:
          - video-generation
          - veo

  - name: Pack Bidi Streaming Demo
    description: |
      ADK 雙向串流示範應用：透過 FastAPI WebSocket 與 ADK Runner 的 BIDI 串流，支援文字、音訊與影像的即時多模態互動。
      後端具備會話管理（Vertex AI Session Service 或 In-Memory），並依模型能力自動切換 AUDIO/TEXT 回應模態與轉錄設定。
    code_ref: workspace/python/agents/pack-bidi-streaming/
    type: App
    models:
      - gemini-live-2.5-flash
    tools:
      - name: get_weather
        type: FunctionTool
        description: 模擬網路搜尋以獲取天氣資訊。
      - name: get_current_time
        type: FunctionTool
        description: 透過時區處理獲取精確的地區時間。
      - name: google_search
        type: GoogleSearchTool
        description: 執行 Google 搜尋以取得最新資訊。
    server-port: 8000
    tags:
      - bidi
      - streaming
      - websocket
      - fastapi
      - multimodal
      - audio
      - image
      - vertex-ai

  - name: Pack RAG Document Retrieval
    description: |
      文檔檢索代理（RAG）：以 Vertex AI RAG Engine 作為外部知識來源，透過 `VertexAiRagRetrieval` 從指定的 RAG Corpus 檢索相關文件區塊，並由 Gemini 彙整後輸出帶引用（URL）的回答。
      內建可觀測性：使用 OpenInference session 與 Arize 追蹤，方便在開發與部署時監控代理效能。
    code_ref: workspace/python/agents/pack-rag
    type: App
    models:
      - gemini-2.0-flash-001
    tools:
      - name: retrieve_rag_documentation
        type: VertexAiRagRetrieval
        description: 使用 VertexAiRagRetrieval 從 Vertex AI RAG Corpus 檢索與問題相關的文件與參考資料（需設定環境變數 `RAG_CORPUS`）。
    server-port: 8000
    tags:
      - rag
      - vertex-ai
      - vertex-ai-rag
      - retrieval
      - citations
      - observability
      - arize
      - fastapi

  - name: Skills Agent
    description: 一個可以使用專業技能 (Specialized skills) 的代理人。
    code_ref: workspace/python/agents/skills-agent/skills_agent
    type: Agent
    models:
      - gemini-2.5-flash
    tools:
      - name: my_skill_toolset
        type: SkillToolset
        description: |
          包含專業技能的工具集，提供問候與天氣查詢功能。
          技能列表：
          - greeting-skill: 讀取參考資料並生成友善的問候語
          - weather-skill: 從參考資料中提取並提供天氣資訊
    tags:
      - skills
      - toolset
      - greeting
      - weather
      - modular
      - skill-management