Strands Agents SDK TypeScript 完整教學

 1strands-ts/src/
 2├── agent/                    # Agent 核心邏輯
 3│   ├── agent.ts              # Agent 類別主體（>800 行）
 4│   ├── agent-as-tool.ts      # Agent 作為 Tool 的包裝
 5│   ├── tool-caller.ts        # Tool 呼叫代理
 6│   ├── printer.ts            # 串流輸出印刷
 7│   └── snapshot.ts           # Agent 快照
 8├── models/                   # Model Provider 實作
 9│   ├── model.ts              # 抽象基類 Model<T>
10│   ├── bedrock.ts            # Amazon Bedrock
11│   ├── anthropic.ts          # Anthropic 直連
12│   ├── openai/               # OpenAI（Chat + Responses API）
13│   ├── google/               # Google Gemini
14│   ├── vercel.ts             # Vercel AI SDK
15│   ├── streaming.ts          # 串流事件定義
16│   └── defaults.ts           # 模型預設參數
17├── tools/                    # Tool 系統
18│   ├── tool.ts               # Tool 抽象基類
19│   ├── function-tool.ts      # FunctionTool（原始 JSON Schema）
20│   ├── zod-tool.ts           # ZodTool（Zod Schema 自動轉換）
21│   ├── tool-factory.ts       # tool() 工廠函式
22│   ├── mcp-tool.ts           # MCP Tool 包裝
23│   └── structured-output-tool.ts  # 結構化輸出工具
24├── multiagent/               # 多 Agent 編排
25│   ├── graph.ts              # Graph DAG 執行引擎
26│   ├── swarm.ts              # Swarm 動態路由引擎
27│   ├── nodes.ts              # AgentNode / MultiAgentNode
28│   ├── edge.ts               # Edge 條件路由
29│   └── state.ts              # 多 Agent 狀態管理
30├── a2a/                      # Agent-to-Agent 協定
31│   ├── a2a-agent.ts          # 遠端 A2A Agent 包裝
32│   ├── server.ts             # A2A Server
33│   └── express-server.ts     # Express 整合
34├── hooks/                    # 生命週期 Hook 系統
35│   ├── events.ts             # 20+ 事件類別
36│   └── registry.ts           # Hook 註冊表
37├── conversation-manager/     # 對話管理策略
38│   ├── sliding-window-*.ts   # 滑動視窗（預設）
39│   └── summarizing-*.ts      # 摘要壓縮
40├── session/                  # 會話持久化
41│   ├── session-manager.ts    # 會話管理器
42│   ├── file-storage.ts       # 檔案系統儲存
43│   └── s3-storage.ts         # AWS S3 儲存
44├── vended-tools/             # 內建工具
45│   ├── bash/                 # Shell 執行
46│   ├── file-editor/          # 檔案編輯
47│   ├── http-request/         # HTTP 請求
48│   └── notebook/             # 筆記本
49├── vended-plugins/           # 內建插件
50│   ├── skills/               # Agent Skills
51│   ├── context-offloader/    # Context 卸載
52│   └── goal/                 # 目標判斷
53├── vended-interventions/     # 內建介入
54│   ├── hitl/                 # Human-in-the-Loop
55│   └── steering/             # 行為引導
56├── sandbox/                  # 沙箱執行環境
57│   ├── posix-shell.ts        # POSIX Shell
58│   ├── docker.ts             # Docker 容器
59│   └── ssh.ts                # SSH 遠端
60├── telemetry/                # OpenTelemetry 整合
61├── retry/                    # 重試策略
62└── interventions/            # 介入框架

1# 建立新專案
2mkdir my-agent && cd my-agent
3npm init -y
4
5# 安裝核心 SDK
6npm install @strands-agents/sdk
7
8# 安裝 Zod（用於 type-safe tool 定義）
9npm install zod

1# 方法 1：AWS CLI profile
2aws configure
3
4# 方法 2：環境變數
5export AWS_ACCESS_KEY_ID="your-access-key"
6export AWS_SECRET_ACCESS_KEY="your-secret-key"
7export AWS_REGION="us-east-1"

1# 安裝 OpenAI peer dependency
2npm install openai
3
4# 設定 API Key
5export OPENAI_API_KEY="sk-..."

1# 安裝 Google GenAI peer dependency
2npm install @google/genai
3
4# 設定 API Key
5export GOOGLE_API_KEY="..."

1# 安裝 Anthropic peer dependency
2npm install @anthropic-ai/sdk
3
4# 設定 API Key
5export ANTHROPIC_API_KEY="sk-ant-..."

 1// tsconfig.json
 2{
 3  "compilerOptions": {
 4    "target": "ES2022",
 5    "module": "NodeNext",
 6    "moduleResolution": "NodeNext",
 7    "strict": true,
 8    "esModuleInterop": true,
 9    "outDir": "./dist",
10    "rootDir": "./src"
11  },
12  "include": ["src/**/*"]
13}

1// package.json 中加入
2{
3  "type": "module",
4  "scripts": {
5    "start": "tsx src/index.ts",
6    "build": "tsc"
7  }
8}

1// src/index.ts
2import { Agent } from '@strands-agents/sdk'
3
4const agent = new Agent()
5const result = await agent.invoke('Hello! What is 2 + 2?')
6console.log(result.toString())

1npx tsx src/index.ts

 1import { Agent, tool } from '@strands-agents/sdk'
 2import { z } from 'zod'
 3
 4// 1. 用 Zod Schema 定義 Tool 的輸入格式
 5//    z.object() 定義物件結構，z.string().describe() 加上描述讓 LLM 知道每個欄位的用途
 6const weatherTool = tool({
 7  name: 'get_weather',                          // Tool 名稱，LLM 會用此名稱呼叫
 8  description: 'Get current weather for a city', // Tool 描述，幫助 LLM 判斷何時使用
 9  inputSchema: z.object({
10    city: z.string().describe('City name, e.g., "Taipei"'),
11    unit: z.enum(['celsius', 'fahrenheit'])      // 限定只能選這兩個值
12           .default('celsius')
13           .describe('Temperature unit'),
14  }),
15  // 2. callback 的 input 參數已自動推斷型別為 { city: string; unit: 'celsius' | 'fahrenheit' }
16  callback: (input) => {
17    // 實際應用中這裡會呼叫真正的天氣 API
18    return `${input.city}: 28°C, sunny`
19  },
20})
21
22// 3. 建立 Agent，將 Tool 注入
23const agent = new Agent({
24  systemPrompt: 'You are a helpful weather assistant. Always use the get_weather tool.',
25  tools: [weatherTool],
26})
27
28// 4. 呼叫 Agent — 它會自動判斷是否需要使用 Tool
29const result = await agent.invoke('What is the weather in Taipei?')
30console.log(result.toString())
31// Agent 會呼叫 get_weather({ city: "Taipei", unit: "celsius" })
32// 然後用工具結果組合成自然語言回答

 1import { Agent, StructuredOutputError } from '@strands-agents/sdk'
 2import { z } from 'zod'
 3
 4// 1. 定義期望的輸出 Schema
 5const MeetingSchema = z.object({
 6  title: z.string().describe('Meeting title'),
 7  date: z.string().describe('Meeting date in ISO 8601 format'),
 8  attendees: z.array(z.object({
 9    name: z.string(),
10    role: z.string(),
11  })).describe('List of attendees'),
12  actionItems: z.array(z.string()).describe('Action items from the meeting'),
13  priority: z.enum(['low', 'medium', 'high']).describe('Meeting priority'),
14})
15
16// 2. 建立 Agent 時傳入 structuredOutputSchema
17const agent = new Agent({
18  structuredOutputSchema: MeetingSchema,
19})
20
21// 3. invoke 後取得型別安全的結構化輸出
22try {
23  const result = await agent.invoke(
24    'Parse this: Team standup on June 18th with Alice (PM) and Bob (Dev). ' +
25    'Action items: update roadmap, fix CI pipeline. High priority.'
26  )
27
28  // result.structuredOutput 的型別已自動推斷
29  const meeting = result.structuredOutput
30  console.log(meeting.title)       // "Team Standup"
31  console.log(meeting.date)        // "2026-06-18"
32  console.log(meeting.attendees)   // [{ name: "Alice", role: "PM" }, ...]
33  console.log(meeting.priority)    // "high"
34} catch (error) {
35  // 4. 多次重試後仍驗證失敗，拋出 StructuredOutputError
36  if (error instanceof StructuredOutputError) {
37    console.error('LLM output validation failed:', error.message)
38  }
39}

 1import { Agent, BedrockModel, Graph } from '@strands-agents/sdk'
 2
 3const model = new BedrockModel({ maxTokens: 2048 })
 4
 5// 1. 定義三個專業 Agent
 6const researcher = new Agent({
 7  model,
 8  id: 'researcher',                            // 必須提供 unique ID
 9  systemPrompt: 'Research the topic thoroughly. Provide key facts and data points.',
10})
11
12const analyst = new Agent({
13  model,
14  id: 'analyst',
15  systemPrompt: 'Analyze the research findings. Identify trends and insights.',
16})
17
18const writer = new Agent({
19  model,
20  id: 'writer',
21  systemPrompt: 'Write a polished summary combining all inputs into a clear report.',
22})
23
24// 2. 建立 Graph，定義節點與邊
25const graph = new Graph({
26  nodes: [researcher, analyst, writer],
27  edges: [
28    // researcher 與 analyst 的結果都會流入 writer
29    ['researcher', 'writer'],
30    ['analyst', 'writer'],
31  ],
32  // 未指定 sources，自動偵測：researcher 和 analyst 沒有 incoming edge → 成為 source
33})
34
35// 3. 執行 — researcher 和 analyst 會並行執行，writer 等待兩者完成後才啟動
36const result = await graph.invoke('AI agents in healthcare')
37
38console.log('Status:', result.status)          // 'complete'
39console.log('Node results:', result.results.length)  // 3
40// 每個 NodeResult 包含：nodeId, status, content, metrics 等
41for (const nodeResult of result.results) {
42  console.log(`${nodeResult.nodeId}: ${nodeResult.status}`)
43}

 1import { Agent, McpClient } from '@strands-agents/sdk'
 2import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 3
 4// 1. 建立 MCP Client，連接到本地 MCP Server
 5const docTools = new McpClient({
 6  transport: new StdioClientTransport({
 7    command: 'uvx',
 8    args: ['awslabs.aws-documentation-mcp-server@latest'],
 9  }),
10})
11
12// 2. 將 MCP Client 直接作為 Tool Source 傳入
13//    Agent 會自動列舉 MCP Server 上的所有 Tool
14const agent = new Agent({
15  systemPrompt: 'You are an AWS expert. Use MCP tools to look up documentation.',
16  tools: [docTools],
17})
18
19// 3. 使用 streaming API — agent.stream() 回傳 AsyncGenerator
20console.log('=== Streaming Response ===')
21for await (const event of agent.stream('How do I set up a VPC?')) {
22  switch (event.type) {
23    // 4. 每個事件有明確的 type discriminator (型別鑑別器)
24    case 'contentBlockEvent':
25      // 文字生成事件
26      if (event.contentBlock.type === 'textBlock') {
27        process.stdout.write(event.contentBlock.text)
28      }
29      break
30    case 'beforeToolCallEvent':
31      // Tool 呼叫前事件 — 可用於 logging 或 UI 顯示
32      console.log(`\n[Calling tool: ${event.toolUse.name}]`)
33      break
34    case 'toolResultEvent':
35      // Tool 回傳結果事件
36      console.log(`[Tool result received]`)
37      break
38  }
39}
40
41// 5. 使用完畢記得斷開 MCP 連線
42await docTools.disconnect()

 1import { Agent, BedrockModel, Swarm } from '@strands-agents/sdk'
 2
 3const model = new BedrockModel({ maxTokens: 1024 })
 4
 5const triage = new Agent({
 6  model, id: 'triage',
 7  description: 'Classifies requests and routes to the right specialist.',
 8  systemPrompt: 'Classify the request. Hand off to billing or technical as appropriate.',
 9})
10
11const billing = new Agent({
12  model, id: 'billing',
13  description: 'Handles billing, invoices, and payment questions.',
14  systemPrompt: 'Answer billing questions. Produce a final response.',
15})
16
17const technical = new Agent({
18  model, id: 'technical',
19  description: 'Handles technical support and troubleshooting.',
20  systemPrompt: 'Answer technical questions. Produce a final response.',
21})
22
23const swarm = new Swarm({
24  nodes: [triage, billing, technical],
25  start: 'triage',       // 起始節點
26  maxSteps: 4,            // 防止無限迴圈
27})
28
29const result = await swarm.invoke('I was charged twice for my subscription')
30// triage 會判斷這是帳單問題，自動 handoff 給 billing

 1import { Agent, BeforeToolCallEvent, AfterToolCallEvent, HookOrder } from '@strands-agents/sdk'
 2
 3const agent = new Agent({ tools: [/* ... */] })
 4
 5// 註冊 Hook — 在每次 Tool 呼叫前後執行
 6agent.on(BeforeToolCallEvent, async (event) => {
 7  console.log(`[Hook] About to call tool: ${event.toolUse.name}`)
 8  console.log(`[Hook] Input:`, JSON.stringify(event.toolUse.input))
 9
10  // 可以修改 event 來影響行為
11  // event.cancel = true  // 取消此次 Tool 呼叫
12}, { order: HookOrder.EARLY })
13
14agent.on(AfterToolCallEvent, async (event) => {
15  console.log(`[Hook] Tool ${event.toolUse.name} completed`)
16  // event.result 包含 Tool 的執行結果
17})
18
19// Hook 清理 — on() 回傳 cleanup 函式
20const cleanup = agent.on(BeforeToolCallEvent, async (event) => { /* ... */ })
21cleanup()  // 移除此 Hook

 1import { Agent, SessionManager, FileStorage } from '@strands-agents/sdk'
 2
 3// 建立 Session Manager — 預設使用檔案系統儲存
 4const sessionManager = new SessionManager({
 5  storage: {
 6    snapshot: new FileStorage({ baseDir: './sessions' }),
 7  },
 8  sessionId: 'my-session-001',
 9  saveLatestOn: 'invocation',  // 每次 invoke 完自動存檔
10})
11
12// Agent 綁定 SessionManager — 會自動 restore 上次的對話狀態
13const agent = new Agent({
14  sessionManager,
15  systemPrompt: 'You are a helpful assistant with memory.',
16})
17
18// 第一次執行
19await agent.invoke('My name is Alice')
20
21// 即使重啟程式，下次建立同樣 sessionId 的 Agent 時
22// 會自動載入上次的對話歷史，Agent 會「記得」使用者叫 Alice

 1import {
 2  Agent,
 3  SlidingWindowConversationManager,
 4  SummarizingConversationManager,
 5} from '@strands-agents/sdk'
 6
 7// 方案 A：滑動視窗 — 保留最近 N 則訊息（預設 40）
 8const agentA = new Agent({
 9  conversationManager: new SlidingWindowConversationManager({
10    windowSize: 20,  // 只保留最近 20 則訊息
11  }),
12})
13
14// 方案 B：摘要壓縮 — 超過上限時用 LLM 摘要舊訊息
15const agentB = new Agent({
16  conversationManager: new SummarizingConversationManager({
17    // 當 token 數接近 context window 上限時觸發摘要
18  }),
19})

 1import { Agent, DefaultModelRetryStrategy, ExponentialBackoff } from '@strands-agents/sdk'
 2
 3const agent = new Agent({
 4  retryStrategy: new DefaultModelRetryStrategy({
 5    maxRetries: 3,
 6    backoff: new ExponentialBackoff({
 7      baseMs: 1000,    // 起始等待 1 秒
 8      maxMs: 30000,    // 最長等待 30 秒
 9    }),
10  }),
11})

 1import { A2AAgent } from '@strands-agents/sdk/a2a'
 2
 3// Client 端：連接遠端 A2A Agent
 4const remoteAgent = new A2AAgent({
 5  url: 'http://localhost:9000',
 6})
 7
 8const result = await remoteAgent.invoke('Analyze this dataset')
 9console.log(result.toString())
10
11// remoteAgent 實作 InvokableAgent 介面
12// 可直接用在 Graph / Swarm 的 nodes 陣列中

1import { PosixShellSandbox } from '@strands-agents/sdk/sandbox'
2
3const sandbox = new PosixShellSandbox()
4const result = await sandbox.execute({
5  command: 'echo "Hello from sandbox"',
6  timeout: 5000,
7})
8console.log(result.stdout)  // "Hello from sandbox"

1// Skills Plugin — 讓 Agent 具備技能框架
2import { SkillsPlugin } from '@strands-agents/sdk/vended-plugins/skills'
3
4// Goal Plugin — 自動判斷 Agent 是否達成目標
5import { GoalPlugin } from '@strands-agents/sdk/vended-plugins/goal'
6
7// Context Offloader — 自動將過長的 context 卸載到外部儲存
8import { ContextOffloaderPlugin } from '@strands-agents/sdk/vended-plugins/context-offloader'

1# strandly — monorepo 開發 CLI（非終端使用者工具）
2strandly setup   # 安裝工具鏈
3strandly build   # 編譯
4strandly test    # 執行測試

1import { McpClient } from '@strands-agents/sdk'
2// 支援 Stdio / SSE / Streamable HTTP 傳輸

1import { A2AServer } from '@strands-agents/sdk/a2a'
2import { A2AExpressServer } from '@strands-agents/sdk/a2a/express'

1import { Agent, tool, BedrockModel, Graph, Swarm, McpClient } from '@strands-agents/sdk'

1sdk-typescript (core engine)
2├── tools (official tools)          → 透過 npm 或直接引用
3├── samples (examples)              → 展示 SDK 用法
4├── agent-builder (terminal agent)  → import SDK 建構互動式 Agent
5├── mcp-server (docs server)        → Agent 可連接的 MCP Server
6├── evals (evaluation)              → 測量 SDK 建構的 Agent 品質
7├── shell (sandbox)                 → SDK 的 Sandbox 模組可使用
8└── agent-sop (workflows)           → 在 SDK Agent 上層定義 SOP

1const swarm = new Swarm({
2  nodes: [triageAgent, billingAgent, technicalAgent, returnAgent],
3  start: 'triage',
4  maxSteps: 6,
5})
6
7// 搭配 SessionManager 實現跨 session 的對話記憶
8// 搭配 HITL Intervention 讓人工客服可隨時接管

 1const graph = new Graph({
 2  nodes: [
 3    dataCollector,    // 蒐集資料（搭配 HTTP Tool + MCP）
 4    factChecker,      // 事實查核
 5    statistician,     // 統計分析
 6    reportWriter,     // 報告撰寫
 7    reviewer,         // 品質審查
 8  ],
 9  edges: [
10    ['dataCollector', 'factChecker'],
11    ['dataCollector', 'statistician'],
12    ['factChecker', 'reportWriter'],
13    ['statistician', 'reportWriter'],
14    ['reportWriter', 'reviewer'],
15  ],
16})
17// dataCollector → factChecker 和 statistician 並行 → reportWriter → reviewer

 1import { Agent, tool } from '@strands-agents/sdk'
 2import { BashTool } from '@strands-agents/sdk/vended-tools/bash'
 3import { FileEditorTool } from '@strands-agents/sdk/vended-tools/file-editor'
 4import { HttpRequestTool } from '@strands-agents/sdk/vended-tools/http-request'
 5
 6const devopsAgent = new Agent({
 7  systemPrompt: `You are a DevOps agent. You can:
 8    - Run shell commands to check system status
 9    - Edit configuration files
10    - Make HTTP requests to monitoring APIs
11    Always explain what you are doing before executing commands.`,
12  tools: [new BashTool(), new FileEditorTool(), new HttpRequestTool()],
13})
14
15// 搭配 PosixShellSandbox 或 DockerSandbox 提供安全執行環境
16await devopsAgent.invoke('Check if nginx is running and restart if needed')

 1// 核心
 2import { Agent, tool, BedrockModel } from '@strands-agents/sdk'
 3
 4// Model Providers
 5import { OpenAIModel } from '@strands-agents/sdk/models/openai'
 6import { GoogleModel } from '@strands-agents/sdk/models/google'
 7import { AnthropicModel } from '@strands-agents/sdk/models/anthropic'
 8
 9// Multi-Agent
10import { Graph, Swarm } from '@strands-agents/sdk/multiagent'
11
12// A2A
13import { A2AAgent, A2AServer } from '@strands-agents/sdk/a2a'
14
15// Session
16import { SessionManager, FileStorage } from '@strands-agents/sdk'
17
18// Telemetry
19import { AgentTrace, AgentMetrics } from '@strands-agents/sdk/telemetry'
20
21// Vended Tools
22import { BashTool } from '@strands-agents/sdk/vended-tools/bash'
23import { FileEditorTool } from '@strands-agents/sdk/vended-tools/file-editor'
24import { HttpRequestTool } from '@strands-agents/sdk/vended-tools/http-request'
25import { NotebookTool } from '@strands-agents/sdk/vended-tools/notebook'
26
27// Sandbox
28import { PosixShellSandbox } from '@strands-agents/sdk/sandbox'
29
30// Zod（peer dependency）
31import { z } from 'zod'

 1import {
 2  ModelError,                   // 模型呼叫錯誤
 3  ContextWindowOverflowError,   // Context Window 溢位
 4  MaxTokensError,               // 達到 Max Tokens 限制
 5  StructuredOutputError,        // 結構化輸出驗證失敗
 6  ConcurrentInvocationError,    // 並行呼叫衝突
 7  ModelThrottledError,          // 模型被限流
 8  ToolValidationError,          // Tool 輸入驗證失敗
 9  ToolNotFoundError,            // Tool 不存在
10} from '@strands-agents/sdk'