ADK Go 入門 03 - 建立第一個 ADK Agent（Go）
ADK Go 入門 03 - 建立第一個 ADK Agent（Go）用 ADK Go SDK 建立第一個可運行的 Agent，只需要幾十行程式碼。本篇從最基本的結構出發，帶你跑起一個能對話的 Agent。 安裝依賴1go get google.golang.org/adk 最小可運行範例123456789101112131415161718192021222324252627282930313233343536373839404142package mainimport ( "context" "os" "google.golang.org/adk/agent" "google.golang.org/adk/agent/llmagent" "google.golang.org/adk/cmd/launcher" "google.golang.org/adk/cmd/launcher/full" "googl...
NanoClaw 替換底層 AI 模型（MiniMax、第三方 API）
NanoClaw 替換底層 AI 模型（MiniMax、第三方 API）NanoClaw 原本只支援 Claude API。為了節省成本，我們擴充了內建的 credential-proxy，新增 OVERRIDE_MODEL 機制，讓 agent 可以透明地切換到任何相容 OpenAI API 格式的第三方模型（如 MiniMax）。 架構1234容器 agent (Claude Agent SDK) → credential-proxy (host:3001) → 原始 Claude API （預設） → 第三方 API （設定 OVERRIDE_MODEL 後） agent 程式碼完全不知道底下換了模型，credential-proxy 在中間做所有轉換。 實作過程為什麼需要動 credential-proxyClaude Agent SDK 在發出請求時，會把 model 名稱（如 claude-sonnet-4-6）一起帶在 request body 裡。如果只是把 ANTHROPIC_BASE_URL 換成 MiniMax 的網址，SD...
ADK Go 入門 02 - ADK 三大核心概念：Agent、Tool、Model
ADK Go 入門 02 - ADK 三大核心概念：Agent、Tool、ModelADK 的整個系統由三個概念支撐：Model（思考引擎）、Tool（行動能力）、Agent（決策主體）。理解三者的分工，是設計 Agent 系統的基礎。 Model：思考引擎Model 是 LLM 的抽象層，負責接收 prompt 並產生回應。在 ADK 中，Model 不直接被使用者呼叫，而是被 Agent 持有。 ADK 內建 Gemini 系列模型的實作，也可以擴充支援其他 LLM。 123Model └── 接收對話 + 工具定義 └── 回傳文字 / 工具呼叫指令 Tool：行動能力Tool 是 Agent 能夠執行的具體動作。LLM 本身只能產生文字，透過 Tool 才能真正操作外部世界。 Tool 的常見形式： 自訂 Go 函式（例：查詢資料庫、計算運費） 內建工具（例：GoogleSearch） 其他 Agent 包裝成的 Tool（Sub-agent as tool） Toolset 是多個 Tool 的集合，通常對應某個外部系統（例：一個 MCP 伺服器暴露的所有操...
ADK Go 入門 01 - 什麼是 Google ADK
ADK Go 入門 01 - 什麼是 Google ADKGoogle ADK（Agent Development Kit）是 Google 推出的開源框架，專門用來建構、編排和部署 AI Agent。它的核心價值不在於讓你「呼叫 LLM」，而是讓你設計一套能夠主動決策、使用工具、協同運作的 Agent 系統。 為什麼不直接呼叫 LLM API直接呼叫 LLM API 只是一問一答：你送 prompt，模型回 text。一旦任務需要多步驟、使用外部工具、或由多個角色協作，就需要自己管理狀態、工具呼叫、錯誤重試、對話歷史⋯⋯ADK 把這些基礎設施都打包好了。 面向 直接呼叫 API 使用 ADK 工具呼叫 自己解析 function call 框架自動處理 多輪對話 手動維護 messages[] 框架管理 session 多 Agent 協作 自行設計路由邏輯 內建 transfer 機制 可觀測性 自己埋 log 內建 OTel 整合 Web UI 自建 內建 launcher ADK 適合什麼場景 需要呼叫外部工具（資料庫、API、搜尋）的 ...
JSONL LLM Log 持久化方案
JSONL LLM Log 持久化方案OTel 將 LLM 的 prompt 與 response 送到 Aspire Dashboard 可即時查看，但資料不持久。透過自訂 JSONLExporter，可將每筆 LLM Log Record 寫入 JSONL 檔案，供長期保存與提示詞版本分析使用。 動機OTel 將 LLM 的 prompt 與 response 送到 Aspire Dashboard 可即時查看，但資料不持久。 JSONL 持久化的目的： 歷史對話存檔：保留所有 LLM 的 input/output，供後續分析 提示詞優化分析：比對不同 prompt 版本在相同情境下的輸出差異 版本追蹤：每筆 log 帶有 git commit hash，可精確對應到當時的提示詞版本，評估修改效果 架構：OTel 雙路徑輸出ADK 預設的 OTLP pipeline 和自訂 JSONL pipeline 是兩條獨立路徑： 123456789ADK Framework（產生 OTel Log Records） │ ├──→ ADK 內建 OTLP ...
Aspire Dashboard — 本地 OTel 後端
Aspire Dashboard — 本地 OTel 後端Aspire Dashboard 是 .NET Aspire 生態系的一個獨立 UI 工具，用於視覺化 OpenTelemetry 資料（Traces、Logs、Metrics）。雖然源自 .NET 生態，但它接收標準 OTLP 協定，任何語言的應用程式都可以把遙測資料送進來。 選擇原因 零安裝：一行 docker run，即可啟動完整 UI 輕量：比完整 Jaeger + 儲存後端的 stack 簡單很多 UI 完整：Traces waterfall、Log viewer、關聯查詢一應俱全 接受 OTLP：標準協定，不綁定語言或框架 docker-compose 設定12345678910services: aspire: image: mcr.microsoft.com/dotnet/aspire-dashboard:latest container_name: my-aspire environment: DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONY...
OTel Custom Log Processor — 跨 Span 注入 Context
OTel Custom Log Processor — 跨 Span 注入 ContextOTel Log Record 預設不繼承 Span 的自訂屬性。透過自訂 Log Processor，可在每筆 Log 被送出前，從 Span Context 讀取指定 attribute 並注入，解決 Log 缺少 session ID 等關聯資訊的問題。 問題描述OTel Log Record 預設不帶 Span 的自訂屬性。例如： Trace Span 上帶有 session_id（由 ADK 在 StartInvokeAgentSpan 時寫入） Log Record 雖然與同一個 Span 關聯，但不會自動繼承 Span 的 attribute 結果：JSONL log 中的 session 欄位為空，無法按 session 分組查詢。 解決方案：實作自訂 Log Processor透過包裝標準 BatchProcessor，在每筆 Log Record 被送出前，從當前 Span Context 讀取 attribute，注入到 Log Record： 12345678...
OpenTelemetry 可觀測性三種訊號（Traces、Metrics、Logs）與 Exporters
OpenTelemetry 可觀測性三種訊號（Traces、Metrics、Logs）與 ExportersOpenTelemetry（OTel）是一套開源的可觀測性標準與 SDK，統一了蒐集 Traces、Metrics、Logs 的方式，讓應用程式可以不綁定特定後端（Jaeger、Zipkin、Datadog 等）地輸出遙測資料。 三種訊號（Signals）1. Traces & SpansTrace 代表一次完整的操作鏈（例如：處理一個使用者請求的全過程）。 Span 是 Trace 的最小單位，記錄一段工作的開始/結束時間與屬性： 12345Trace: 處理訂單請求├── Span: route_request (root span)│ ├── Span: parse_order_message│ ├── Span: call_llm (LLM 推論)│ └── Span: create_order (DB 寫入) 每個 Span 帶有： trace_id：所屬 Trace 的唯一 I...
Agent Tool 無上下文記憶，需改用 Sub-agent
Agent Tool 無上下文記憶，需改用 Sub-agent在 ADK 中，透過 agenttool.New() 包裝的 Agent Tool 每次被呼叫時為無狀態執行，無法存取父 agent 的對話記憶；需要上下文的流程應改用 Sub-agent。 問題描述在 ADK 中，透過 agenttool.New() 將 Agent 包裝成 Agent Tool 後，該 agent 在被呼叫時沒有父 agent 的對話記憶： Agent Tool 每次被呼叫都是無狀態的獨立執行 無法存取父 agent 的對話歷史（session history） 適合「給一個輸入、取得一個輸出」的無狀態任務（例如：查資料、分析圖片） 對比：Sub-agent vs Agent Tool Sub-agent（sub_agents） Agent Tool（agenttool.New()） 上下文記憶 ✅ 共享父 agent session ❌ 無，每次獨立執行 呼叫方式 transfer_to_agent(agent_name=...) 直接呼叫工具 適合情境 需要對話歷史的複...
ADK Sub-agent STOP 錯誤：停用 Thinking Mode
ADK Sub-agent STOP 錯誤：停用 Thinking Mode使用 Gemini 2.5 Flash 模型時，若 sub-agent 啟用思考模式（Thinking Mode），有時會導致該 sub-agent 回傳空的 content，觸發 ADK 的 STOP 錯誤，整個對話流程中斷。 錯誤現象 Sub-agent 被 transfer 進來後無回應 Log 顯示 finish_reason 為 STOP 但 content 為空 問題只在 sub-agent 上出現，root agent 不受影響 根本原因Gemini 2.5 Flash 的思考模式會在回應中產生內部推理（thinking tokens），但在 ADK 的 multi-agent 架構中，sub-agent 的思考輸出有時無法正確轉換為可回傳的 content，導致空回應。 解決方案：對 Sub-agent 停用思考模式在建立 sub-agent 時，透過 GenerateContentConfig 將 ThinkingBudget 設為 0： 12345678910111213think...