strands-agents/devtools 完整教學

Repository: https://github.com/strands-agents/devtools Stars: 13 | Forks: 15 | Language: Python License: Apache-2.0 | Last Updated: 2026-06-15 Tags: agentic, agents, ai, strands-agents Homepage: https://strandsagents.com

1. 專案概覽 (Project Overview)

1.1 這是什麼

strands-agents/devtools 是 Strands Agents 生態系的 共用 DevOps 基礎設施 (shared DevOps infrastructure)，提供跨組織 (cross-organization) 的 GitHub Actions、可重用工作流 (reusable workflows)、以及 AI agent 執行引擎。它讓 Strands Agents 旗下所有 12 個 repo 能夠透過統一的 CI/CD 管線 (pipeline) 運行 AI agent、自動化 issue 分類、以及執行評估 (evaluation) 基準測試。

簡單來說：devtools 是 Strands Agents 生態系的「基礎建設層」 – 就像一棟建築的水電管線與電梯系統，其他 repo (sdk-python, sdk-typescript, tools, docs 等) 都依賴它來完成自動化工作。

1.2 誰開發的

由 AWS 的 Strands Agents 團隊開發，作為其開源 AI agent 框架 (framework) 的一部分。這個組織目前包含 12 個 repo，涵蓋 Python/TypeScript SDK、工具庫 (tools library)、文件網站 (documentation site)、範例集 (samples)、以及本 repo 的 DevOps 工具。

1.3 核心元件

devtools 包含三大元件 (components) 與一個評估基礎設施 (eval infrastructure)：

1.4 為什麼重要

在 AI agent 生態系中，DevOps 自動化 是經常被忽略但極為關鍵的一環。devtools 展示了幾個重要的設計模式 (design patterns)：

1. AI-native CI/CD: 不只用 AI 生成程式碼，而是讓 AI agent 直接在 CI pipeline 中執行任務
2. 讀寫分離 (read-write separation): Agent 在唯讀沙盒 (read-only sandbox) 中運行，寫入操作延遲到安全環境中執行
3. 結構化輸出安全性 (structured output security): Issue labeler 用 Pydantic enum 做白名單 (allowlist)，LLM 只能回傳預定義的標籤
4. 可觀測性 (observability): 整合 Langfuse telemetry，所有 agent 動作都可追蹤

2. 核心架構 (Core Architecture)

2.1 整體架構圖

graph TB
    subgraph "GitHub Events"
        IC[Issue Comment
/strands command]
        IO[Issue Opened/Edited]
        WD[Workflow Dispatch]
    end

    subgraph "devtools Actions"
        AC[authorization-check
權限驗證]
        IL[issue-labeler
LLM 標籤分類]
        
        subgraph "strands-command"
            SIP[strands-input-parser
輸入解析]
            SAR[strands-agent-runner
Agent 執行]
            SF[strands-finalize
寫入與清理]
        end
    end

    subgraph "AWS Services"
        BR[Amazon Bedrock
Claude Opus 4]
        S3[S3 Bucket
Session Storage]
        SM[Secrets Manager
Config & Keys]
        SQS[SQS Queue
Eval Triggers]
    end

    subgraph "Observability"
        LF[Langfuse
Telemetry & Tracing]
        ED[Evals Dashboard
React + CloudFront]
        ER[Eval Runner
Lambda Function]
    end

    IC --> AC --> SIP --> SAR --> SF
    IO --> IL
    WD --> AC

    IL --> BR
    SAR --> BR
    SAR --> S3
    SAR --> SM
    SAR --> SQS

    SQS --> ER
    ER --> LF
    LF --> ED

2.2 Strands Command 執行流程

sequenceDiagram
    participant U as GitHub User
    participant GH as GitHub Actions
    participant Auth as authorization-check
    participant Parser as input-parser
    participant Agent as agent-runner
    participant Fin as finalize
    participant Bedrock as AWS Bedrock
    participant S3 as S3 Sessions

    U->>GH: /strands implement 
    GH->>Auth: Check collaborator role
    
    alt User is authorized
        Auth-->>GH: auto-approve
    else User not recognized
        Auth-->>GH: manual-approval (needs env gate)
    end

    GH->>Parser: Parse command + context
    Parser->>Parser: Add strands-running label
    Parser->>Parser: Generate session_id
    Parser->>Parser: Select SOP system prompt
    Parser-->>GH: Upload strands-parsed-input artifact

    GH->>Agent: Execute (read-only permissions)
    Agent->>S3: Load/create session
    Agent->>Bedrock: Claude Opus 4 (adaptive thinking)
    
    loop Agent Tool Loop
        Bedrock-->>Agent: Tool call (shell, edit, github_tools)
        Agent->>Agent: Execute tool
        Agent-->>Bedrock: Tool result
    end
    
    Agent->>Agent: Capture repo state (tar.gz)
    Agent->>Agent: Save write operations (JSONL)
    Agent-->>GH: Upload artifacts

    GH->>Fin: Apply changes
    Fin->>Fin: Extract repo state
    Fin->>Fin: Push to feature branch
    Fin->>Fin: Execute deferred write ops
    Fin->>Fin: Remove strands-running label

2.3 Issue Labeler 安全架構

Issue labeler 的設計特別值得關注，因為它展示了如何安全地讓 LLM 處理使用者提供的內容 (user-supplied content)：

graph LR
    subgraph "Input Layer"
        IT[Issue Title]
        IB[Issue Body]
    end

    subgraph "Sanitization"
        S1[Strip control chars
regex sanitize]
        S2[Truncate to max_body_length
預設 1000 chars]
    end

    subgraph "LLM Classification"
        SP[System Prompt
含 allowlist 描述]
        SO[Structured Output
Pydantic enum 約束]
    end

    subgraph "Output Layer"
        V[Schema Validation
只允許 enum 值]
        GH[gh issue edit
套用標籤]
    end

    IT --> S1 --> SP
    IB --> S2 --> SP
    SP --> SO --> V --> GH

安全模型重點：

• LLM 沒有工具 (no tools)、沒有 shell 存取、沒有 GitHub API 存取
• 輸出用 Pydantic enum 強制約束在白名單 (allowlist) 內
• 最壞情況只是標籤錯誤 (mislabeling)，不會有任意動作 (arbitrary actions)

3. 安裝與設定 (Installation & Setup)

3.1 前置需求 (Prerequisites)

使用 devtools 不需要在本機安裝任何東西 – 它是純 GitHub Actions 形式的工具。但要設定它，你需要：

• GitHub repository 並有 admin 或 write 權限
• AWS 帳戶 並已啟用 Amazon Bedrock (建議 us-west-2 區域)
• GitHub OIDC Provider 已在 AWS IAM 中設定 (用於安全驗證)

3.2 設定 Issue Labeler

Step 1: 建立 AWS IAM Role

你的 IAM role 需要以下權限 (permissions)：

 1{
 2  "Version": "2012-10-17",
 3  "Statement": [
 4    {
 5      "Effect": "Allow",
 6      "Action": [
 7        "bedrock:InvokeModel",
 8        "bedrock:InvokeModelWithResponseStream"
 9      ],
10      "Resource": "*"
11    }
12  ]
13}

Trust policy 需要允許 GitHub OIDC：

 1{
 2  "Version": "2012-10-17",
 3  "Statement": [
 4    {
 5      "Effect": "Allow",
 6      "Principal": {
 7        "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
 8      },
 9      "Action": "sts:AssumeRoleWithWebIdentity",
10      "Condition": {
11        "StringEquals": {
12          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
13        },
14        "StringLike": {
15          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:*"
16        }
17      }
18    }
19  ]
20}

Step 2: 建立 label 設定檔

在你的 repo 中建立 .github/labelers/area.yml：

 1# 額外指示 (optional)
 2instructions: |
 3  CI dependency bumps should be labeled "chore".
 4  Documentation-only changes should be labeled "docs".
 5
 6# 標籤白名單 (required)
 7labels:
 8  bug:
 9    description: "Something is broken or not working as expected"
10  enhancement:
11    description: "New feature or improvement request"
12  question:
13    description: "User needs help or clarification"
14  docs:
15    description: "Documentation improvements or corrections"
16  chore:
17    description: "Maintenance, dependency updates, CI changes"

Step 3: 建立 GitHub workflow

建立 .github/workflows/issue-labeler.yml：

 1name: Issue Labeler
 2
 3on:
 4  issues:
 5    types: [opened, edited]
 6
 7permissions:
 8  issues: write
 9  id-token: write
10  contents: read
11
12jobs:
13  label:
14    runs-on: ubuntu-latest
15    steps:
16      - uses: actions/checkout@v4
17        with:
18          sparse-checkout: .github/labelers
19          sparse-checkout-cone-mode: false
20
21      - uses: strands-agents/devtools/issue-labeler@main
22        with:
23          aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
24          config_path: '.github/labelers/area.yml'

Step 4: 在 repo settings 中設定 GitHub Secret

• 前往 repo 的 Settings > Secrets and variables > Actions
• 新增 AWS_ROLE_ARN secret，值為你的 IAM role ARN

3.3 設定 Strands Command

這是較為複雜的設定，需要更多 AWS 資源：

Step 1: 建立 S3 bucket (session storage)

1aws s3 mb s3://your-strands-sessions-bucket --region us-west-2

Step 2: 建立 Secrets Manager secret

1aws secretsmanager create-secret \
2  --name strands-agent-config \
3  --secret-string '{
4    "AGENT_SESSIONS_BUCKET": "your-strands-sessions-bucket",
5    "LANGFUSE_PUBLIC_KEY": "pk-xxx",
6    "LANGFUSE_SECRET_KEY": "sk-xxx",
7    "LANGFUSE_HOST": "https://us.cloud.langfuse.com"
8  }' \
9  --region us-east-1

Step 3: 建立 IAM role (權限更廣，包含 S3、Secrets Manager、Bedrock)

需要的 permissions 包含：

• secretsmanager:GetSecretValue
• bedrock:InvokeModel / bedrock:InvokeModelWithResponseStream
• s3:PutObject / s3:GetObject / s3:DeleteObject / s3:ListBucket

Step 4: 建立 strands-command workflow

建立 .github/workflows/strands-command.yml（完整範例見 strands-command/README.md），包含四個 jobs：

1. authorization-check – 驗證使用者權限
2. setup-and-process – 解析輸入
3. execute-readonly-agent – 唯讀沙盒中執行 agent
4. finalize – 套用變更、清理標籤

Step 5: 設定 GitHub Secrets

• AWS_ROLE_ARN: IAM role ARN
• AWS_SECRETS_MANAGER_SECRET_ID: Secrets Manager secret 的 ID 或 ARN

4. 使用方式與程式碼範例 (Usage & Code Examples)

4.1 Issue Labeler – 多維度平行分類

最典型的用法是對同一個 issue 從不同維度 (dimensions) 進行分類，每個維度獨立執行，互不衝突：

 1# .github/workflows/issue-labeler.yml
 2name: Multi-Dimension Issue Labeler
 3
 4on:
 5  issues:
 6    types: [opened, edited]
 7
 8permissions:
 9  issues: write
10  id-token: write
11  contents: read
12
13jobs:
14  # Job 1: 按領域 (area) 分類
15  label-area:
16    runs-on: ubuntu-latest
17    steps:
18      - uses: actions/checkout@v4
19        with:
20          sparse-checkout: .github/labelers
21          sparse-checkout-cone-mode: false
22      - uses: strands-agents/devtools/issue-labeler@main
23        with:
24          aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
25          config_path: '.github/labelers/area.yml'
26          max_labels: '3'     # 一個 issue 可能跨多個領域
27
28  # Job 2: 按類型 (type) 分類 -- 只選一個
29  label-type:
30    runs-on: ubuntu-latest
31    steps:
32      - uses: actions/checkout@v4
33        with:
34          sparse-checkout: .github/labelers
35          sparse-checkout-cone-mode: false
36      - uses: strands-agents/devtools/issue-labeler@main
37        with:
38          aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
39          config_path: '.github/labelers/type.yml'
40          max_labels: '1'     # 類型只選一個
41
42  # Job 3: 按語言 (language) 分類 -- 只選一個
43  label-language:
44    runs-on: ubuntu-latest
45    steps:
46      - uses: actions/checkout@v4
47        with:
48          sparse-checkout: .github/labelers
49          sparse-checkout-cone-mode: false
50      - uses: strands-agents/devtools/issue-labeler@main
51        with:
52          aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
53          config_path: '.github/labelers/language.yml'
54          max_labels: '1'

設計重點解析：

• 每個 job 獨立執行，不會互相等待或衝突
• max_labels 可針對不同分類維度設定上限
• sparse-checkout 只拉 labeler 設定檔，節省 checkout 時間
• 三個 job 平行 (parallel) 跑，總執行時間取決於最慢的那個

4.2 Issue Labeler – 行內設定 (Inline Config)

不想維護額外的 YAML 設定檔時，可以直接在 workflow 中定義：

 1- uses: strands-agents/devtools/issue-labeler@main
 2  with:
 3    aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
 4    max_labels: '2'
 5    model_id: 'global.anthropic.claude-sonnet-4-6'  # 預設值，可換其他 Bedrock 模型
 6    max_body_length: '2000'   # 送給 LLM 的 issue body 最大字元數
 7    config: |
 8      instructions: |
 9        This repository is a Python SDK.
10        Issues about documentation should always get "docs" label.
11        Performance-related issues should get "performance" label.
12      labels:
13        bug: "Something is broken or produces incorrect results"
14        enhancement: "New feature request or improvement"
15        docs: "Documentation is missing, incorrect, or needs improvement"
16        performance: "Performance degradation or optimization needed"
17        question: "User has a question about usage"

行內設定解析：

• instructions 是可選的 (optional)，用來給 LLM 額外的上下文 (context)
• labels 是必要的 (required)，key 是標籤名稱，value 是描述
• 標籤必須先在 GitHub repo 上存在 – action 只負責「打標籤」，不負責「建立標籤」
• max_body_length: '2000' 可以讓 LLM 看到更多內容，但會增加 token 消耗

4.3 Strands Command – 在 Issue 上觸發 Agent

使用者在 issue comment 中輸入 /strands 命令，即可觸發 AI agent：

1/strands implement Create a REST API endpoint for user management with:
21. CRUD operations for users
32. JWT authentication
43. Input validation
54. Unit tests with 90% coverage
65. OpenAPI documentation

這會觸發以下流程：

1. authorization-check 驗證評論者是否為 collaborator (maintain/triage/write/admin 角色)
2. input-parser 偵測到 implement 關鍵字，載入 task-implementer.sop.md 作為 system prompt
3. agent-runner 在唯讀沙盒中啟動 Claude Opus 4 agent
4. Agent 使用 TDD (Test-Driven Development; 測試驅動開發) 流程：
   • 讀取 repo 的 CONTRIBUTING.md / DEVELOPMENT.md 了解慣例
   • 建立 feature branch
   • 撰寫測試 (RED)
   • 撰寫實作 (GREEN)
   • 重構 (REFACTOR)
   • 建立 PR
5. finalize 把 agent 的變更推送到 feature branch、執行延遲的 GitHub API 寫入操作

可用的 agent 類型 (SOP types)：

4.4 classify.py 的安全設計 – 結構化輸出白名單

devtools 最精妙的設計之一是 issue-labeler 的安全模型。以下是核心程式碼解析：

 1def build_classification_model(valid_labels: frozenset) -> type[BaseModel]:
 2    """Build a Pydantic model whose label field is an enum of the allowlist.
 3
 4    SECURITY: the enum *is* the allowlist, so the structured-output schema
 5    rejects any value the model invents that is not a configured label.
 6    """
 7    # 動態建立 enum，成員來自設定檔的標籤名稱
 8    # 例如 valid_labels = {"bug", "enhancement", "docs"}
 9    # 則 label_enum 的合法值只有 Label.bug, Label.enhancement, Label.docs
10    label_enum = enum.Enum("Label", {name: name for name in sorted(valid_labels)})
11
12    class Classification(BaseModel):
13        labels: list[label_enum] = Field(
14            default_factory=list,
15            description="Labels that apply to the issue, drawn only from the allowed set.",
16        )
17
18    return Classification

設計重點逐行解析：

1. frozenset 作為輸入 – 不可變集合 (immutable set)，防止在建構過程中被篡改
2. 動態 enum.Enum – 從設定檔的標籤名稱動態建立 enum class，使得 LLM 的結構化輸出 (structured output) 只能包含這些值
3. Pydantic BaseModel – 利用 Strands SDK 的 agent.structured_output() 方法，強制 LLM 回傳符合 schema 的 JSON
4. 安全核心 – 即使 issue body 包含 prompt injection (提示注入攻擊)，LLM 也只能回傳 enum 內的值，最壞情況是「標錯標籤」而非「執行任意操作」

對比傳統做法（後端過濾）：

1# 傳統做法 (不安全) -- LLM 可能回傳任意字串，靠後端過濾
2result = agent("classify this issue")
3labels = [l for l in result.labels if l in valid_labels]  # 可能漏掉邊界案例
4
5# devtools 做法 (安全) -- schema 層級就拒絕非法值
6result = agent.structured_output(Classification, "classify this issue")
7# result.labels 保證只包含 enum 成員，不需要額外過濾

5. 進階功能 (Advanced Features)

5.1 讀寫分離的安全執行模式 (Read-Write Separation)

strands-command 最重要的設計是 讀寫分離 (read-write separation)：

1. Agent Runner Job (execute-readonly-agent)

   • 執行時只有 contents: read / issues: read / pull-requests: read 權限
   • Agent 可以讀取 repo 內容、shell 執行、HTTP 請求
   • 所有 GitHub 寫入操作 (create PR, add comment 等) 被序列化為 write_operations.jsonl artifact
   • 所有檔案變更被打包為 repository_state.tar.gz artifact

2. Finalize Job (finalize)

   • 在獨立 job 中取得 contents: write / issues: write / pull-requests: write
   • 解壓 repo state、推送到 feature branch
   • 從 JSONL 逐一執行延遲的寫入操作

這個設計確保即使 agent 被 prompt injection 攻擊，也無法在執行階段進行未授權的寫入。

5.2 Session 管理與多輪對話

Agent runner 使用 S3 Session Manager (S3 會話管理器) 支援多輪對話 (multi-turn conversation)：

1# agent_runner.py 中的 session 設定
2session_manager = S3SessionManager(
3    session_id=session_id,      # 例如 "implementer-123"
4    bucket=s3_bucket,           # S3 bucket 名稱
5    prefix=s3_prefix,           # GitHub repo 路徑作為前綴
6)

Session ID 的命名慣例是 {agent_type}-{issue_number}，例如 implementer-42 或 reviewer-123。同一個 issue 上的多次 /strands 命令會共用 session，讓 agent 能夠「記住」先前的對話。

5.3 Langfuse 遙測 (Telemetry) 整合

agent_runner.py 內建 Langfuse 遙測追蹤 (tracing)：

 1def _setup_langfuse_telemetry() -> bool:
 2    """Set up Langfuse telemetry if environment variables are configured."""
 3    # 用 base64 編碼的 API key 設定 OTLP exporter
 4    langfuse_auth = base64.b64encode(
 5        f"{langfuse_public_key}:{langfuse_secret_key}".encode()
 6    ).decode()
 7
 8    os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = f"{langfuse_host}/api/public/otel"
 9    os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {langfuse_auth}"
10
11    StrandsTelemetry().setup_otlp_exporter()

Trace attributes (追蹤屬性) 包含：

• session.id: 格式為 {owner}_{repo}:{agent_type}-{issue_number}
• user.id: GitHub actor (觸發者)
• langfuse.tags: repo、workflow、run ID 等標籤

5.4 CDK Evals – Agent 品質評估基礎設施

cdk-evals/ 是一套完整的 AWS CDK 基礎設施，用來評估 agent 的表現品質：

架構組成：

評估器 (Evaluators) 包含四種：

1. concise_response – 評估 agent 回覆是否簡潔
2. expected_trajectory – 比對 agent 的工具呼叫軌跡是否符合預期
3. release_notes_structure – 檢查 release notes 格式是否正確
4. turn_efficiency – 評估 agent 完成任務所需的對話輪數效率

觸發方式：agent_runner.py 完成後自動透過 SQS 發送評估觸發：

1def _send_eval_trigger(session_id: str, eval_type: str) -> None:
2    """Send evaluation trigger to SQS queue after agent completion."""
3    message_body = json.dumps({
4        "session_id": session_id,
5        "eval_type": eval_type
6    })
7    sqs_client.send_message(QueueUrl=queue_url, MessageBody=message_body)

5.5 Agent SOPs (Standard Operating Procedures; 標準作業程序)

devtools 定義了四種 agent SOP，每種都有嚴格的步驟要求：

Task Implementer (task-implementer.sop.md)：

• Setup > Explore > Plan > Code > Commit > PR
• 強制 TDD 流程：先寫測試 (RED) > 實作 (GREEN) > 重構
• 自動檢查 CONTRIBUTING.md、DEVELOPMENT.md、AGENTS.md
• 支援 progress notebook 追蹤進度

Task Refiner (task-refiner.sop.md)：

• Read Issue > Analyze > Research > Clarify > Iterate
• 用於需求不清楚時的釐清與對齊

Task Reviewer (task-reviewer.sop.md)：

• Code review agent，審查 PR 的程式碼品質

Release Notes Generator (task-release-notes.sop.md)：

• 分析 merged PRs > 分類變更 > 擷取程式碼範例 > 產生格式化 release notes

5.6 Handoff to User – 人機協作控制

handoff_to_user.py 實作了 agent 將控制權交回使用者的機制：

1@tool(context=True)
2def handoff_to_user(message: str, tool_context: ToolContext) -> str:
3    """Hand off control to the user with a message."""
4    request_state = {
5        "stop_event_loop": True
6    }
7    tool_context.invocation_state["request_state"] = request_state
8    return ""

這是一個精巧的設計 – 當 agent 遇到需要人類判斷的情境 (例如測試失敗、需求不清楚)，它會：

1. 在 issue 上留言說明情況
2. 呼叫 handoff_to_user 停止事件迴圈 (event loop)
3. 等待使用者回覆後再次被觸發

6. Agent 可呼叫性分析 (Agent Callability)

6.1 CLI 可呼叫性

devtools 不提供 CLI 工具 – 它是純 GitHub Actions 生態系的工具。但間接地，/strands 命令本身就是一種「在 GitHub 上的 CLI」：

1# 在 issue comment 中使用
2/strands                          # 預設行為 (issue=refine, PR=implement)
3/strands implement                # 觸發 implementer agent
4/strands release-notes            # 觸發 release notes 生成
5/strands <keyword> <additional>   # 關鍵字 + 額外指示

也可透過 workflow_dispatch 手動觸發：

1gh workflow run strands-command.yml \
2  --field issue_id=123 \
3  --field command="Implement the requested feature" \
4  --field session_id="custom-session-id"

6.2 MCP 可呼叫性

devtools 本身不暴露 MCP (Model Context Protocol) server。但 agent_runner.py 內部載入的工具 (tools) 可以被 Strands Agent 呼叫：

6.3 API 可呼叫性

無獨立 API。所有功能透過 GitHub Actions 觸發。

6.4 程式化整合

如果你要在自己的 repo 中使用 devtools，整合方式是在 workflow YAML 中引用 action：

1# 引用方式
2uses: strands-agents/devtools/issue-labeler@main      # issue labeler
3uses: strands-agents/devtools/authorization-check@main  # auth check
4uses: strands-agents/devtools/strands-command/actions/strands-agent-runner@main  # agent runner

建議使用 @main 或特定 commit SHA (如 @abc1234) 而非 tag，因為此 repo 目前較新，尚未建立穩定的版本標籤 (version tags)。

7. 與生態系的關係 (Ecosystem Relationships)

7.1 Strands Agents 生態系總覽

graph TB
    subgraph "核心 SDK"
        SP[sdk-python
Python SDK]
        ST[sdk-typescript
TypeScript SDK]
    end

    subgraph "工具與擴充"
        TL[tools
內建工具庫]
        SM[samples
範例專案]
    end

    subgraph "DevOps 基礎設施"
        DT[devtools
本 repo]
    end

    subgraph "文件與社群"
        DC[docs
文件網站]
        AG[agent-builder
視覺化建構器]
    end

    DT -->|CI/CD for| SP
    DT -->|CI/CD for| ST
    DT -->|CI/CD for| TL
    DT -->|CI/CD for| DC
    DT -->|Issue labeling for| SP
    DT -->|Issue labeling for| ST

    SP -->|uses| TL
    ST -->|uses| TL
    SM -->|demonstrates| SP
    SM -->|demonstrates| ST
    AG -->|builds on| SP

7.2 與各 repo 的具體關係

7.3 依賴方向

devtools 是「被依賴方 (dependency)」而非「依賴者 (dependent)」。其他 repo 的 workflow 引用 devtools 的 actions，但 devtools 本身不依賴其他 strands-agents repo（除了 strands-agents Python SDK 和 strands-tools 作為 runtime 依賴）。

8. 優缺點分析 (Strengths & Limitations)

8.1 優點 (Strengths)

8.2 限制 (Limitations)

8.3 安全考量

官方文件明確指出：

“This workflow should only be used with trusted sources and should use AWS guardrails to help avoid prompt injection risks.”

這意味著 strands-command 不適合用在公開 repo (public repos) 上讓任意使用者觸發。建議只在以下情境使用：

• 組織內部的私有 repo
• 或設定嚴格的 authorization-check 權限 (只允許 admin/maintain 角色)

9. 實戰應用場景 (Real-world Use Cases)

9.1 場景一：開源專案的自動 Issue 分類

情境：你維護一個有數百個 issues 的開源專案，需要快速分類新 issue 的領域 (area) 和類型 (type)。

做法：

1. 建立兩個 labeler 設定檔：
   • .github/labelers/area.yml – 定義 area-backend, area-frontend, area-docs, area-ci
   • .github/labelers/type.yml – 定義 bug, enhancement, question, chore
2. 建立 workflow，兩個 job 平行跑
3. 新 issue 開啟後，數秒內自動打上正確的標籤

效益：

• 節省 maintainer 每天 15-30 分鐘的手動分類時間
• 標籤一致性提高（不再有「有人忘記打標籤」的問題）
• 可搭配 GitHub Projects 的 auto-add 功能，標籤驅動看板 (Kanban)

9.2 場景二：PR 自動實作與 Code Review

情境：團隊使用 GitHub Issues 管理需求，希望 AI agent 能自動嘗試實作並發 PR。

做法：

1. 設定 strands-command workflow
2. 需求方在 issue 中寫好規格
3. 工程師在 issue comment 中輸入 /strands implement
4. Agent 自動：
   • 閱讀 issue 描述與 repo 慣例
   • 建立 feature branch
   • 用 TDD 流程寫測試與實作
   • 發 PR 並在 issue 上留言進度
5. 如果測試失敗或需要澄清，agent 會 handoff_to_user 等待人類介入
6. PR 提交後，可再用 /strands 在 PR 上觸發 reviewer agent

效益：

• 將簡單的 feature request 從「issue 到 PR」的時間從數天縮短到分鐘
• 強制 TDD 流程，提高程式碼品質
• Session 持久化讓 agent 能跨多次互動「記住」上下文

9.3 場景三：自動化 Release Notes 生成

情境：每次發版 (release) 時需要整理所有 merged PRs，寫成結構化的 release notes。

做法：

1. 建立一個 release tracking issue，描述版本範圍 (例如 v1.2.0...HEAD)
2. 在 issue 上留言 /strands release-notes
3. Agent 自動：
   • 查詢指定範圍內的所有 merged PRs
   • 按重要性分類 (breaking changes > features > fixes > docs)
   • 從每個 PR 擷取程式碼範例並驗證
   • 生成格式化的 markdown release notes
   • 發布為 issue comment

效益：

• 消除手動整理 changelog 的繁瑣工作
• Release notes 品質一致，包含驗證過的程式碼範例
• 透過 eval pipeline 追蹤 release notes 的品質分數

附錄：關鍵檔案索引