Strands Agents Samples 完整教學

 1strands-agents/samples/
 2├── python/
 3│   ├── 01-learn/           # 18 個基礎教學
 4│   │   ├── 01-first-agent/          # 第一個 Agent
 5│   │   ├── 02-tools-and-mcp/        # 工具與 MCP
 6│   │   ├── 03-model-providers/      # 模型供應商切換
 7│   │   ├── 04-streaming/            # 串流處理
 8│   │   ├── 05-guardrails/           # 安全護欄
 9│   │   ├── 06-memory/               # 記憶系統
10│   │   ├── 07-aws-services/         # AWS 服務整合
11│   │   ├── 08-observability/        # 可觀測性
12│   │   ├── 09-bidi-streaming/       # 雙向串流
13│   │   ├── 10-agents-as-tools/      # Agent 作為工具
14│   │   ├── 11-swarm/                # Swarm 多 Agent 協作
15│   │   ├── 12-graph/                # Graph 拓撲 Agent
16│   │   ├── 13-human-in-the-loop/    # 人在迴圈中
17│   │   ├── 14-plugins/              # 外掛系統
18│   │   ├── 15-skills/               # 技能模組
19│   │   ├── 16-hooks-lifecycle/      # Hook 生命週期
20│   │   ├── 17-conversation-management/ # 對話管理
21│   │   └── 18-self-improving-agents/   # 自我改進 Agent
22│   ├── 02-deploy/          # 部署模式（Lambda / Fargate / AgentCore）
23│   ├── 03-integrate/       # 整合範例
24│   ├── 04-industry-use-cases/  # 產業應用（金融 / 醫療 / 物流 / 行銷）
25│   ├── 05-technical-use-cases/ # 技術應用（RAG / steering）
26│   ├── 06-evaluate/        # 評估與測試
27│   ├── 07-ux-demos/        # 全端 UI 展示
28│   └── 08-edge/            # 邊緣裝置 / 機器人
29└── typescript/
30    ├── 01-learn/           # TypeScript 基礎教學
31    │   ├── 01-first-agent/          # 第一個 Agent
32    │   ├── 02-custom-tools/         # 自訂工具
33    │   ├── 03-model-providers/      # 模型供應商
34    │   ├── 04-streaming/            # 串流處理
35    │   ├── 05-agent-state/          # Agent 狀態管理
36    │   └── 06-browser-agent/        # 瀏覽器 Agent
37    └── 02-deploy/          # 部署模式（AgentCore）

1git clone https://github.com/strands-agents/samples.git
2cd samples

1# 使用 uv（推薦）
2uv venv
3source .venv/bin/activate
4
5# 或使用 venv
6python -m venv venv
7source venv/bin/activate

1# 安裝 Strands Agents SDK 和官方工具集
2pip install strands-agents strands-agents-tools
3
4# 若使用 TypeScript 範例
5cd typescript/01-learn/01-first-agent
6npm install

1cd python/01-learn/01-first-agent
2pip install -r requirements.txt

1# 確保 AWS credentials 已設定
2aws configure
3# 或使用環境變數
4export AWS_ACCESS_KEY_ID="your-key"
5export AWS_SECRET_ACCESS_KEY="your-secret"
6export AWS_REGION="us-east-1"

1export OPENAI_API_KEY="sk-..."

1from strands import Agent
2from strands.models.litellm import LiteLLMModel
3
4model = LiteLLMModel(model_id="openai/gpt-4o")
5agent = Agent(model=model)

1# 先啟動 Ollama
2ollama serve
3ollama pull llama3.1

1from strands import Agent
2from strands.models.ollama import OllamaModel
3
4model = OllamaModel(model_id="llama3.1")
5agent = Agent(model=model)

 1from strands import Agent
 2
 3# 建立一個 Agent — 只需一行
 4agent = Agent()
 5
 6# 與 Agent 對話 — 只需呼叫
 7response = agent("Hello! Tell me a joke.")
 8
 9# 印出回應
10print(response)

 1import logging
 2from ddgs import DDGS
 3from ddgs.exceptions import DDGSException, RatelimitException
 4from strands import Agent, tool
 5
 6# 設定 logging 等級 — 追蹤 Agent 內部行為
 7logging.getLogger("strands").setLevel(logging.INFO)
 8
 9# 使用 @tool 裝飾器定義自訂工具
10@tool
11def websearch(
12    keywords: str,
13    region: str = "us-en",
14    max_results: int | None = None
15) -> str:
16    """Search the web to get updated information.
17
18    Args:
19        keywords (str): The search query keywords.
20        region (str): The search region: wt-wt, us-en, uk-en, ru-ru, etc..
21        max_results (int | None): The maximum number of results to return.
22
23    Returns:
24        List of dictionaries with search results.
25    """
26    try:
27        results = DDGS().text(keywords, region=region, max_results=max_results)
28        return results if results else "No results found."
29    except RatelimitException:
30        return "RatelimitException: Please try again after a short delay."
31    except DDGSException as d:
32        return f"DuckDuckGoSearchException: {d}"
33    except Exception as e:
34        return f"Exception: {e}"
35
36# 建立帶有 system prompt 和工具的 Agent
37recipe_agent = Agent(
38    system_prompt="""You are RecipeBot, a helpful cooking assistant.
39    Help users find recipes based on ingredients and answer cooking questions.
40    Use the websearch tool to find recipes when users mention ingredients
41    or to look up cooking information.""",
42    tools=[websearch],
43)
44
45if __name__ == "__main__":
46    print("\nRecipeBot: Ask me about recipes or cooking! Type 'exit' to quit.\n")
47    while True:
48        user_input = input("\nYou > ")
49        if user_input.lower() == "exit":
50            print("Happy cooking!")
51            break
52        response = recipe_agent(user_input)
53        print(f"\nRecipeBot > {response}")

 1from strands import Agent
 2from strands_tools import shell, file_write
 3
 4MODEL_ID = "global.anthropic.claude-opus-4-8"
 5
 6SYSTEM_PROMPT = """You are a self-extending research agent.
 7
 8You can CREATE new tools by writing Python files to ./tools/. Each file should
 9define one or more functions decorated with `@tool` from the strands package.
10Tools become available instantly after the file is saved.
11
12Template for a new tool:
13
14```python
15from strands import tool
16
17@tool
18def my_tool(argument: str) -> str:
19    \"\"\"Short description of what this tool does.
20
21    Args:
22        argument: What this argument means.
23
24    Returns:
25        A string result.
26    \"\"\"
27    return f"result for {argument}"

 1
 2**逐行解析重點：**
 3
 4- **`load_tools_from_directory=True`**：這是 Strands SDK 的獨特功能。啟用後，Agent 會監控 `./tools/` 目錄，任何新增的 Python 檔案只要包含 `@tool` 裝飾器的函式，就會自動載入成為可用工具。
 5- **自我擴展邏輯 (self-extension logic)**：system prompt 告訴 Agent「當你沒有需要的能力時，自己寫一個工具」。Agent 透過 `file_write` 工具將新 Python 檔案寫入 `./tools/`，框架自動偵測並載入。
 6- **安全注意事項 (security note)**：這種模式賦予 Agent 執行任意程式碼的能力，僅適用於開發和實驗環境。生產環境必須搭配 sandbox (沙箱) 和 guardrails (安全護欄)。
 7
 8### 4.4 範例四：Swarm 多 Agent 協作
 9
10**檔案位置**：`python/01-learn/11-swarm/`
11
12```python
13import logging
14from strands import Agent
15from strands.multiagent import Swarm
16
17# 啟用除錯日誌 — 觀察 Agent 之間的 handoff
18logging.getLogger("strands.multiagent").setLevel(logging.DEBUG)
19logging.basicConfig(
20    format="%(levelname)s | %(name)s | %(message)s",
21    handlers=[logging.StreamHandler()]
22)
23
24# 建立專業化的 Agent 團隊
25researcher = Agent(
26    name="researcher",
27    system_prompt="You are a research specialist. "
28                  "Find relevant information and facts."
29)
30coder = Agent(
31    name="coder",
32    system_prompt="You are a coding specialist. "
33                  "Write clean, well-documented code."
34)
35reviewer = Agent(
36    name="reviewer",
37    system_prompt="You are a code review specialist. "
38                  "Review code for bugs and improvements."
39)
40architect = Agent(
41    name="architect",
42    system_prompt="You are a system architecture specialist. "
43                  "Design scalable system architectures."
44)
45
46# 建立 Swarm — 設定安全參數
47swarm = Swarm(
48    [researcher, coder, reviewer, architect],
49    max_handoffs=20,           # 最多 20 次 handoff
50    max_iterations=20,         # 最多 20 次迭代
51    execution_timeout=900.0,   # 總時限 15 分鐘
52    node_timeout=300.0,        # 每個 Agent 最多 5 分鐘
53    repetitive_handoff_detection_window=8,  # 偵測乒乓行為
54    repetitive_handoff_min_unique_agents=3  # 最近 8 次必須有 3 個不同 Agent
55)
56
57# 執行 Swarm 任務
58result = swarm("Design and implement a simple REST API for a todo app")
59
60# 查看結果
61print(f"Status: {result.status}")
62print(f"Node history: {[node.node_id for node in result.node_history]}")
63print(f"Total iterations: {result.execution_count}")
64print(f"Execution time: {result.execution_time}ms")
65print(f"Token usage: {result.accumulated_usage}")

 1Agent 建構 ──> AgentInitializedEvent（一次性）
 2
 3agent("問題")
 4│
 5├─ BeforeInvocationEvent         # 可修改 messages
 6│  └─ MessageAddedEvent          # 使用者輸入加入歷史
 7│
 8├─ BeforeModelCallEvent          # 每次呼叫模型前
 9│  └─ AfterModelCallEvent        # 可設定 retry
10│     └─ MessageAddedEvent       # 模型回應加入歷史
11│
12├─ BeforeToolCallEvent           # 可設定 cancel_tool
13│  └─ AfterToolCallEvent         # 可設定 retry / 修改 result
14│     └─ MessageAddedEvent       # 工具結果加入歷史
15│
16└─ AfterInvocationEvent          # 可設定 resume（自動重啟）

 1from strands.hooks import HookProvider, AgentInitializedEvent, BeforeToolCallEvent
 2
 3class SafetyGuard(HookProvider):
 4    """封裝安全相關的多個 Hook 為可重用元件"""
 5    
 6    def register_hooks(self, agent):
 7        agent.add_hook(AgentInitializedEvent, self.on_init)
 8        agent.add_hook(BeforeToolCallEvent, self.on_before_tool)
 9    
10    def on_init(self, event: AgentInitializedEvent):
11        print("Safety guard initialized")
12    
13    def on_before_tool(self, event: BeforeToolCallEvent):
14        # 阻擋危險工具
15        if event.tool_name in ["shell", "file_write"]:
16            event.cancel_tool = True
17            event.cancel_reason = "This tool is blocked by safety policy"

1skills/
2├── returns-policy/
3│   ├── SKILL.md              # 技能描述 + 指令
4│   └── references/
5│       └── returns-checklist.md  # 參考文件
6└── technical-troubleshooting/
7    ├── SKILL.md
8    └── references/
9        └── escalation-guide.md

 1@tool
 2def system_prompt(action: str, prompt: str | None = None) -> dict:
 3    """Manage the agent's own system prompt at runtime.
 4
 5    Args:
 6        action: One of "view", "update", "add_context", "reset".
 7        prompt: The new prompt text (required for update / add_context).
 8    """
 9    if action == "update":
10        os.environ["SYSTEM_PROMPT"] = prompt
11        Path(".prompt").write_text(prompt)
12        return {"status": "success", "content": [{"text": f"Prompt updated"}]}
13    
14    if action == "add_context":
15        existing = os.environ.get("SYSTEM_PROMPT", "")
16        merged = f"{existing}\n\n{prompt}"
17        os.environ["SYSTEM_PROMPT"] = merged
18        Path(".prompt").write_text(merged)
19        return {"status": "success", "content": [{"text": "Context appended."}]}
20    # ... 其他 action

 1# 執行 Python script 範例
 2cd python/01-learn/01-first-agent/02-simple-interactive-usecase
 3python recipe_bot.py
 4
 5# 執行 Jupyter Notebook 範例
 6cd python/01-learn/11-swarm
 7jupyter notebook swarm.ipynb
 8
 9# TypeScript 範例
10cd typescript/01-learn/01-first-agent
11npm install && npx ts-node src/firstAgent.ts

 1from strands import Agent
 2from strands.tools.mcp import MCPClient
 3
 4# 連接 MCP server
 5mcp_client = MCPClient("npx -y @modelcontextprotocol/server-filesystem /tmp")
 6
 7# 將 MCP 工具注入 Agent
 8with mcp_client:
 9    tools = mcp_client.list_tools()
10    agent = Agent(tools=tools)
11    agent("List files in /tmp")

 1                    ┌─────────────┐
 2                    │  harness-sdk │ ◄── 核心 SDK
 3                    │  (Python)    │
 4                    └──────┬──────┘
 5                           │
 6              ┌────────────┼────────────┐
 7              │            │            │
 8        ┌─────▼─────┐ ┌───▼───┐ ┌──────▼──────┐
 9        │   tools    │ │ shell │ │ agent-sop   │
10        │ (工具集)   │ │(安全) │ │ (SOP 工作流)│
11        └─────┬─────┘ └───┬───┘ └──────┬──────┘
12              │            │            │
13              └────────────┼────────────┘
14                           │
15                    ┌──────▼──────┐
16                    │  ★ samples  │ ◄── 組合所有元件的範例
17                    │  (本 repo)  │
18                    └──────┬──────┘
19                           │
20              ┌────────────┼────────────┐
21              │            │            │
22        ┌─────▼─────┐ ┌───▼────┐ ┌─────▼─────┐
23        │   docs    │ │ evals  │ │mcp-server │
24        │ (文件)    │ │(評估)  │ │(MCP 輔助) │
25        └───────────┘ └────────┘ └───────────┘

 1# 安裝核心依賴
 2pip install strands-agents strands-agents-tools
 3
 4# 執行特定範例
 5cd python/01-learn/01-first-agent
 6pip install -r requirements.txt
 7python 02-simple-interactive-usecase/recipe_bot.py
 8
 9# 啟動 Jupyter Notebook
10jupyter notebook python/01-learn/11-swarm/swarm.ipynb
11
12# TypeScript 範例
13cd typescript/01-learn/01-first-agent
14npm install && npx ts-node src/firstAgent.ts