{"id":51060232,"url":"https://github.com/yazelin/telegram-ai-agent-starter","last_synced_at":"2026-06-23T01:02:07.183Z","repository":{"id":361900663,"uuid":"1256347763","full_name":"yazelin/telegram-ai-agent-starter","owner":"yazelin","description":"Starter template for building Telegram AI agents with FastAPI, CLI/HTTP LLM providers, tools, and deployment notes.","archived":false,"fork":false,"pushed_at":"2026-06-09T11:56:07.000Z","size":263,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T13:18:38.632Z","etag":null,"topics":["ai-agent","fastapi","llm","starter-template","telegram-bot"],"latest_commit_sha":null,"homepage":"https://yazelin.github.io/telegram-ai-agent-starter/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yazelin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T17:35:06.000Z","updated_at":"2026-06-09T11:56:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yazelin/telegram-ai-agent-starter","commit_stats":null,"previous_names":["yazelin/telegram-ai-agent-starter"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/yazelin/telegram-ai-agent-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazelin%2Ftelegram-ai-agent-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazelin%2Ftelegram-ai-agent-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazelin%2Ftelegram-ai-agent-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazelin%2Ftelegram-ai-agent-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yazelin","download_url":"https://codeload.github.com/yazelin/telegram-ai-agent-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazelin%2Ftelegram-ai-agent-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34671045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","fastapi","llm","starter-template","telegram-bot"],"created_at":"2026-06-23T01:02:06.665Z","updated_at":"2026-06-23T01:02:07.177Z","avatar_url":"https://github.com/yazelin.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Brand banner](assets/banner.svg)\n\n# Telegram AI Agent Starter\n\nBuild a Telegram AI assistant that can call LLMs and tools.\n\n## 繁中定位\n\n**Telegram AI Agent 入門模板** 面向台灣繁中受眾。\n\n- 主要受眾：適合想把 Telegram 變成 AI 工作入口的台灣工程師、接案者與小團隊。\n- 核心承諾：從一個 bot token 開始，做出會回覆、會呼叫工具、可部署的 AI Agent。\n- CTA 頁：https://yazelin.github.io/telegram-ai-agent-starter/\n\n\n\n## 公開教學文件\n\n這個 repo 的教學內容直接公開，讓你可以先自己照著跑；如果需要手把手 debug、改成你的公司或個人場景，再考慮工作坊或顧問協助。\n\n- 網頁版教學：https://yazelin.github.io/telegram-ai-agent-starter/tutorial.html\n- Markdown 教學：[`docs/`](docs/)\n- 快速開始：[`docs/01-quickstart.md`](docs/01-quickstart.md)\n- 常見踩雷：[`docs/05-common-pitfalls.md`](docs/05-common-pitfalls.md)\n- 後半段(PydanticAI 對照組):docs/08-pydantic-ai-agent.md\n\n## Who this is for\n\nEngineers who want a deployable Telegram AI workflow bot.\n\n## Features\n\n- FastAPI webhook（`POST /webhook/telegram`）+ polling dev mode（`uv run python -m app.polling`，含錯誤退避）\n- 四種 `AI_PROVIDER`：`echo`（離線純對話）/ `claude-cli` / `gemini-cli`（純對話）/ `http`（OpenAI-compatible）\n- **真正的 tool-calling agent 迴圈（僅 `http` 模式）**：把 `tools=` 送給 LLM，模型自己決定呼叫 `app/tools.py` 的工具，結果接回對話再產生最終答案；其他三種 provider 為純 chat\n- 手動 `/tool time` 指令隨時可用；Allow-list user IDs 擋陌生人\n- Docker-ready starter for workshops\n- PydanticAI agent 版同功能重寫(optional `pydantic` extra)— 見 `docs/08-pydantic-ai-agent.md`\n\n## Quick start\n\n本專案用 [uv](https://docs.astral.sh/uv/) 管理依賴與虛擬環境（取代 venv + pip）。\n\n安裝 uv（一次就好）：\n\n- Ubuntu / macOS：\n\n  ```bash\n  curl -LsSf https://astral.sh/uv/install.sh | sh\n  ```\n\n- Windows（PowerShell）：\n\n  ```powershell\n  powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n  ```\n\n裝完重開終端機，`uv --version` 印得出版本就 OK。\n\n取得專案、裝依賴、跑起來：\n\n```bash\ngit clone https://github.com/yazelin/telegram-ai-agent-starter.git\ncd telegram-ai-agent-starter\nuv sync\ncp .env.example .env\nuv run uvicorn app.main:app --reload --port 8000\n```\n\n`uv sync` 會依 `pyproject.toml` + `uv.lock` 自動建立 `.venv` 並裝好套件（毋須手動 venv/activate）；`uv run` 直接在那個環境裡執行。**以上 `uv sync` / `uv run` 在 Ubuntu 與 Windows 完全相同。** 加新套件用 `uv add \u003c套件\u003e`。\n\n本機 polling 開發模式（不需公開網址）：`uv run python -m app.polling`。\n\n（沒裝 uv 的話 `pip install .` 也能裝，但本教學以 uv 為主。）\n\nSee the source files and `.env.example` for the minimal runnable path.\n\n### 後半段:PydanticAI agent 版(對照組)\n\n```bash\nuv sync --extra pydantic\nPYTHONPATH=. uv run python agent_smoke_test_pydantic.py   # 框架接線 smoke(免 API key)\n# .env 設 AI_PROVIDER=pydantic 後:\nuv run uvicorn app.main:app                               # bot 改用 PydanticAI agent\n```\n\n## Learn / get help\n\nThis repo is also a CTA page for workshops and consulting:\n\n- GitHub Pages: https://yazelin.github.io/telegram-ai-agent-starter/\n- Contact: yazelin@ching-tech.com\n\n## License\n\nMIT\n\n\n## Brand / CTA design\n\n- Landing page: https://yazelin.github.io/telegram-ai-agent-starter/\n- CI spec: [DESIGN.md](DESIGN.md)\n- Banner: [assets/banner.svg](assets/banner.svg)\n- Logo: [assets/logo.svg](assets/logo.svg)\n\n---\n## 關於作者\n\n這個範本由 **林亞澤（Yaze Lin）** 維護 — 出身機電自動化系統整合，現在把同一套工程方法用在 AI 產品上。\n\n- 任職於 **擎添工業 ChingTech**（1984 年成立的機電自動化公司：PLC 程式、機械手臂、AGV 無人搬運、半導體封測／PCB／面板／光學產線整合）。\n- 技術筆記與更多範例：[yazelin.github.io](https://yazelin.github.io) · GitHub [@yazelin](https://github.com/yazelin)\n\n## 從範本到正式產品\n\n\u003e 把「會自己呼叫工具的 agent」做到正式產品這條線，我們做成了 AgentOS 與 Mori Desktop。\n\n如果你想看同樣的想法做成正式、上線中的產品：\n\n- **CTOS** — 企業 AI 工作平台：macOS 風格 Web 桌面、知識庫 RAG 檢索、產業專屬 Agent、LINE Bot 整合，資料留在台灣。[ching-tech.com](https://ching-tech.com) · [品牌站](https://ching-tech.github.io)\n- **CTOS-Lite / CT JINN** — 把公司裝進 LINE 的個人版 AI 助理，加 LINE 即可試用：[@285fjkky](https://line.me/R/ti/p/@285fjkky)\n- **Mori Desktop** — 個人 AI 管家桌面應用（Tauri 2 + Rust + React）：[github.com/yazelin/mori-desktop](https://github.com/yazelin/mori-desktop)\n- **AgentOS** — 跨 CLI 的 agent 治理平台（開發中）\n\n\u003e 想把這個範本落地成你公司的內部系統，或想上一堂從 0 到部署的課？\n\u003e 來信 yazelin@ching-tech.com，或追蹤上面的連結。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyazelin%2Ftelegram-ai-agent-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyazelin%2Ftelegram-ai-agent-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyazelin%2Ftelegram-ai-agent-starter/lists"}