做出會回覆、會呼叫工具、可部署的 AI Agent。先手刻 OpenAI tool-calling 迴圈看懂 agent 怎麼讀 tool_calls、跑工具、把結果接回對話，再用框架拿生產力。
這頁讓你 5 分鐘知道這是什麼、能做出什麼、真的會動，而且不靠任何 token 就能跑起來看到真實輸出。要逐行、踩雷、部署、FAQ 的完整版，在實戰手冊裡。
想把 Telegram 變成 AI 工作入口，常卡在「怎麼把一個 bot 變成會呼叫工具的 agent？tool-calling 迴圈到底在做什麼？要不要先學一套框架才動得了？」
這個範本是一支可跑的 Telegram AI Agent：FastAPI 收 webhook、一個會讀 tool_calls、跑工具、把結果接回對話的 agent 迴圈。教材分兩軌 —— 前半段從零手刻 OpenAI 相容的 tool-loop，後半段用 PydanticAI 重寫同一個 agent 當對照組，讓你清楚知道框架替你做了什麼、又沒替你做什麼（工具邏輯永遠是你自己的）。適合想把 Telegram 變成 AI 工作入口的台灣工程師、接案者與小團隊。
/tool 指令。需要 uv、Python 3.10+、Git。第一次驗證不需要任何 token（.env 預設 AI_PROVIDER=echo）。
git clone https://github.com/yazelin/telegram-ai-agent-starter.git
cd telegram-ai-agent-starter
uv sync
cp .env.example .envPYTHONPATH=. AI_PROVIDER=echo uv run python /tmp/try_echo.py/tmp/try_echo.py 在 repo 外呼叫核心函式 ask_ai 與 run_tool（完整內容見 docs/01）。
ask_ai echo: 'Echo: hello from a learner'
run_tool time: '2026-06-02T03:30:19+08:00'
run_tool help: 'Try /ask your question or /tool time'time 工具回一個 ISO 8601 時間字串。到這裡程式邏輯已完整跑通，完全不需要任何外部帳號。前半段你手刻 OpenAI 相容的 tool-calling 迴圈（app/agent.py 的 run_http_agent）：自己組 messages、for _ in range(MAX_TOOL_ITERS) 迴圈、手讀 tool_calls、手 dispatch。後半段用 PydanticAI 重寫同一個 agent，體會「同樣的事，少寫一大截樣板」。
| 面向 | 手刻 app/agent.py | PydanticAI |
|---|---|---|
| tool-loop | 手寫迴圈 + 手接 role:tool | 框架擁有迴圈 |
| 工具註冊 | TOOL_SCHEMAS（手寫 JSON）+ run_tool 兩處 | @agent.tool_plain 一個 decorator，schema 由型別自動生 |
| 工具邏輯 run_tool | 自己寫 | 共用：框架工具是薄 wrapper 呼叫 run_tool |
核心一句：框架移除的是「手寫 schema + 手刻迴圈」，不是你的工具邏輯。PydanticAI 的工具是薄 wrapper 呼叫既有 run_tool，所以兩版行為一致，而樣板少一大截。完整對照在 docs/08。
這頁是快速了解；下面每一章都是完整內容，在 GitHub 上點開就能讀。
這頁是快速了解。逐行讀懂、架構拆解、踩雷清單、部署、改成你的場景都在實戰手冊裡。