Strands Agent Builder 完整教學

 1agent-builder/
 2├── src/strands_agents_builder/
 3│   ├── strands.py              # CLI 主程式入口 (main entry point)
 4│   ├── tools.py                # Tool registry — 收集所有可用 tool
 5│   ├── handlers/
 6│   │   └── callback_handler.py # Streaming callback + spinner 動畫
 7│   ├── models/
 8│   │   ├── bedrock.py          # Amazon Bedrock model provider
 9│   │   └── ollama.py           # Ollama local model provider
10│   └── utils/
11│       ├── kb_utils.py         # Knowledge Base 工具函式
12│       ├── model_utils.py      # Model 載入 + 設定管理
13│       └── welcome_utils.py    # 歡迎訊息渲染
14├── tools/                      # 自訂 tool（隨 package 發佈）
15│   ├── rich_interface.py       # Rich 介面工具
16│   ├── store_in_kb.py          # Knowledge Base 儲存工具
17│   ├── strand.py               # 巢狀 agent 工具
18│   └── welcome.py              # 歡迎文字管理工具
19├── .prompt                     # 預設 system prompt
20├── pyproject.toml              # 套件設定 + 依賴宣告
21└── tests/                      # 單元測試 + 整合測試

1# 安裝 pipx（如果尚未安裝）
2brew install pipx    # macOS
3# 或
4apt-get install pipx  # Ubuntu/Debian
5
6# 安裝 Agent Builder
7pipx install strands-agents-builder

1# 建議使用 uv 建立虛擬環境
2uv venv .venv && source .venv/bin/activate
3
4# 安裝
5uv pip install strands-agents-builder

1git clone https://github.com/strands-agents/agent-builder.git
2cd agent-builder
3pip install -e ".[dev,test]"

1# 方法一：AWS CLI 設定
2aws configure
3# 輸入 Access Key ID, Secret Access Key, Region (建議 us-east-1 或 us-west-2)
4
5# 方法二：環境變數
6export AWS_ACCESS_KEY_ID="your-access-key"
7export AWS_SECRET_ACCESS_KEY="your-secret-key"
8export AWS_REGION="us-west-2"

1# 確認指令可用
2strands --help
3
4# 執行一次性查詢測試
5strands "What time is it?"
6
7# 進入互動模式
8strands

1# 進入互動模式
2strands

1~ 幫我列出目前目錄下的所有 Python 檔案

1~ !ls -la
2~ !git status

1# 直接在命令列傳入查詢
2strands "Create a Python function that calculates fibonacci numbers"
3
4# 搭配管道 (pipe) 輸入
5cat requirements.txt | strands "分析這些依賴的安全性風險"
6
7# 搭配 Knowledge Base
8strands --kb ABCDEFGHIJ "Load my previous calculator tool and add scientific functions"

1strands "Create a tool named sentiment_analyzer that analyzes text sentiment \
2and test it with some examples"

 1# tools/sentiment_analyzer.py
 2from strands import tool
 3
 4@tool
 5def sentiment_analyzer(text: str) -> dict:
 6    """
 7    分析輸入文字的情感傾向 (sentiment)。
 8
 9    Args:
10        text: 要分析的文字內容
11
12    Returns:
13        包含情感分析結果的字典
14    """
15    try:
16        # Agent 可能使用 use_llm 或自行實作邏輯
17        positive_words = ["good", "great", "excellent", "happy", "love"]
18        negative_words = ["bad", "terrible", "awful", "hate", "sad"]
19
20        text_lower = text.lower()
21        pos_count = sum(1 for w in positive_words if w in text_lower)
22        neg_count = sum(1 for w in negative_words if w in text_lower)
23
24        if pos_count > neg_count:
25            sentiment = "positive"
26        elif neg_count > pos_count:
27            sentiment = "negative"
28        else:
29            sentiment = "neutral"
30
31        return {
32            "status": "success",
33            "content": [{"text": f"Sentiment: {sentiment} "
34                                 f"(positive signals: {pos_count}, "
35                                 f"negative signals: {neg_count})"}]
36        }
37    except Exception as e:
38        return {
39            "status": "error",
40            "content": [{"text": f"Error: {str(e)}"}]
41        }

 1# strand tool 的原始碼核心邏輯（簡化版）
 2from strands import Agent, tool
 3from typing import List, Optional
 4
 5@tool
 6def strand(
 7    query: str,
 8    system_prompt: Optional[str] = None,
 9    tool_names: Optional[List[str]] = None,
10) -> dict:
11    """
12    建立並執行一個巢狀 Strands agent。
13
14    Args:
15        query: 要處理的查詢
16        system_prompt: 子 agent 專用的 system prompt
17        tool_names: 要提供給子 agent 的 tool 名稱清單
18    """
19    from strands_agents_builder.tools import get_tools
20    all_tools = get_tools()
21
22    # 選擇指定的 tools，若未指定則使用全部
23    selected_tools = [all_tools[name] for name in tool_names
24                      if name in all_tools] if tool_names else list(all_tools.values())
25
26    # 建立獨立的子 agent
27    agent = Agent(
28        tools=selected_tools,
29        messages=[],                    # 空白對話歷史
30        system_prompt=system_prompt or "You are a helpful assistant."
31    )
32
33    # 執行查詢並回傳結果
34    response = agent(query)
35    return {"status": "success",
36            "content": [{"text": f"Strands result:\n\n{str(response)}"}]}

1~ 用一個專門的 Python 程式碼審查 agent 來分析 main.py 的品質

1# 啟動時連接 Knowledge Base
2strands --kb YOUR_KB_ID
3
4# 在互動模式中
5~ Create a data visualization tool and save it for future use

 1# store_in_kb.py 核心邏輯（簡化版）
 2@tool
 3def store_in_kb(content: str, title: str = None,
 4                knowledge_base_id: str = None) -> dict:
 5    """
 6    將內容存入 Bedrock Knowledge Base（非同步背景執行）。
 7    """
 8    kb_id = knowledge_base_id or os.getenv("STRANDS_KNOWLEDGE_BASE_ID")
 9
10    # 在背景 thread 中執行，不阻塞主迴圈
11    thread = threading.Thread(
12        target=_store_in_kb_background,
13        args=(content, title, kb_id, region_name),
14        daemon=True
15    )
16    thread.start()
17
18    # 立即回傳，不等待完成
19    return {"status": "success",
20            "content": [{"text": "Started background task to store content..."}]}

1# 使用 Ollama（需先安裝 Ollama 並拉取模型）
2strands --model-provider ollama --model-config '{"model_id": "llama3.2"}'
3
4# 使用自訂 provider
5# 先在 .models/ 目錄建立 Python 模組
6mkdir -p .models

1# .models/custom_model.py
2from mymodels import CustomModel
3
4def instance(**config):
5    """必須暴露 instance 函式，回傳 Model 實例。"""
6    return CustomModel(**config)

1# 使用自訂 provider
2strands --model-provider custom_model --model-config '{"api_key": "xxx"}'

 1# CallbackHandler 的核心事件處理（簡化版）
 2class CallbackHandler:
 3    def callback_handler(self, **kwargs):
 4        # 串流文字輸出
 5        if data := kwargs.get("data", ""):
 6            print(data, end="" if not kwargs.get("complete") else "\n")
 7
 8        # Tool 執行追蹤
 9        if tool_use := kwargs.get("current_tool_use", {}):
10            tool_name = tool_use.get("name")
11            tool_input = tool_use.get("input", "")
12            # 啟動 spinner 並即時更新輸入大小
13            self.current_spinner.update(
14                f"🛠️  {tool_name}: {len(tool_input)} chars"
15            )

1{
2    "anthropic_beta": ["interleaved-thinking-2025-05-14"],
3    "thinking": {
4        "type": "enabled",
5        "budget_tokens": 2048
6    }
7}

1# kb_utils.py 中的載入邏輯
2def load_system_prompt():
3    system_prompt = os.getenv("STRANDS_SYSTEM_PROMPT")
4    if not system_prompt:
5        prompt_file = Path(os.getcwd()) / ".prompt"
6        if prompt_file.exists():
7            system_prompt = prompt_file.read_text().strip()
8    return system_prompt or ""

1# 在互動模式中使用 swarm
2~ Create a swarm of 3 agents: one for research, one for coding, 
3  and one for documentation. Have them collaborate on building 
4  a weather dashboard.

1# 在 agent 對話中
2agent.tool.load_tool(name="my_tool", path="/path/to/my_tool.py")
3
4# 載入後立即可用
5agent.tool.my_tool(param="value")

1# 主要進入點
2strands                           # 互動模式
3strands "query"                   # 一次性查詢
4strands --kb ID "query"           # 搭配 Knowledge Base
5strands --model-provider ollama   # 切換模型
6strands --model-config config.json # 自訂模型設定

 1from strands import Agent
 2from strands_agents_builder.tools import get_tools
 3from strands_agents_builder.handlers.callback_handler import callback_handler
 4
 5# 取得所有預設 tools
 6tools = get_tools().values()
 7
 8# 建立 agent 實例
 9agent = Agent(
10    tools=tools,
11    system_prompt="You are a specialized assistant.",
12    callback_handler=callback_handler,
13    load_tools_from_directory=True,
14)
15
16# 執行查詢
17response = agent("Build me a web scraping tool")
18
19# 直接呼叫 tool
20result = agent.tool.shell(command="ls -la")
21result = agent.tool.python_repl(code="print(2+2)")

1dependencies = [
2    "strands-agents[ollama]>=1.0.0",      # 核心 SDK + Ollama 支援
3    "strands-agents-tools>=0.1.0,<1.0.0", # 標準工具庫
4    "rich>=14.0.0,<15.0.0",               # 豐富終端輸出
5    "prompt_toolkit>=3.0.51,<4.0.0",      # 互動式輸入
6    "halo>=0.0.31,<1.0.0"                 # Spinner 動畫
7]

 1# 啟動 Agent Builder
 2strands
 3
 4# 第一步：請 agent 建立監控 tool
 5~ Create a tool named api_monitor that accepts a list of URLs, 
 6  checks their HTTP status codes, and returns a report of any 
 7  endpoints that are not returning 200.
 8
 9# Agent 會自動建立 tools/api_monitor.py 並測試
10
11# 第二步：建立排程 tool
12~ Create a cron job that runs api_monitor every 5 minutes 
13  against these endpoints: https://api.example.com/health, 
14  https://api.example.com/status
15
16# 第三步：加入 Slack 通知
17~ When api_monitor detects a non-200 status, use the slack tool 
18  to send an alert to #ops-alerts channel

 1# 啟動並連接 Knowledge Base
 2strands --kb ABCDEFGHIJ
 3
 4# 建立專用的資料分析 tool
 5~ Build a tool that reads CSV files, performs basic statistical 
 6  analysis (mean, median, std, correlations), and generates 
 7  a summary report in markdown format.
 8
 9# 分析資料
10~ Analyze the experiment data in ./data/experiment_results.csv 
11  and highlight any outliers
12
13# 儲存分析方法論到 KB（自動觸發 store_in_kb）
14~ Save this analysis approach as "Standard Experiment Analysis v1" 
15  for future reference

1strands --kb ABCDEFGHIJ "Load my Standard Experiment Analysis v1 \
2  and apply it to the new data in ./data/experiment_v2.csv"

 1strands
 2
 3# 使用 swarm 建立多 agent 審查管線
 4~ Create a code review swarm with three specialized agents:
 5
 61. Security Agent: Focus on SQL injection, XSS, authentication 
 7   flaws, and secret exposure. Use tools: file_read, python_repl, shell
 8   
 92. Performance Agent: Focus on algorithmic complexity, memory leaks, 
10   and unnecessary I/O. Use tools: file_read, python_repl, shell
11   
123. Readability Agent: Focus on naming conventions, code structure, 
13   documentation, and type hints. Use tools: file_read, editor
14
15Have all three agents review the files in ./src/ and produce 
16a consolidated report sorted by severity.

 1# 成功回傳
 2{
 3    "status": "success",
 4    "content": [
 5        {"text": "主要結果文字"},
 6        {"text": "補充資訊（可選）"}
 7    ]
 8}
 9
10# 失敗回傳
11{
12    "status": "error",
13    "content": [
14        {"text": "錯誤訊息描述"}
15    ]
16}

 1DEFAULT_MODEL_CONFIG = {
 2    "model_id": "us.anthropic.claude-sonnet-4-20250514-v1:0",
 3    "max_tokens": 32768,
 4    "boto_client_config": Config(
 5        read_timeout=900,      # 15 分鐘超時
 6        connect_timeout=900,
 7        retries=dict(max_attempts=3, mode="adaptive"),
 8    ),
 9    "additional_request_fields": {
10        "thinking": {
11            "type": "enabled",
12            "budget_tokens": 2048,
13        },
14        "anthropic_beta": ["interleaved-thinking-2025-05-14"],
15    },
16    "cache_tools": "default",
17    "cache_prompt": "default",
18}