--- title: "自架 LangGraph 撞牆記：langgraph-api 要授權，最後改用 Aegra" url: https://geminixiang.com/posts/langgraph-self-host-aegra/ description: "LangGraph 函式庫是 MIT，但官方的 langgraph-api 伺服器是 Elastic License 2.0，啟動就要驗證 LangSmith 授權。記錄我怎麼發現這件事、為什麼改用開源的 Aegra，以及換過去要注意的地方。" published: 2026-10-19 category: "AI Agent" tags: ["LangGraph", "Aegra", "LangSmith", "Self-hosting", "AI Agent"] --- # 自架 LangGraph 撞牆記：langgraph-api 要授權，最後改用 Aegra 這篇主要想記錄一下自架 LangGraph 時撞到的一道牆 不是完整教學，比較像是踩坑筆記，給之後也想自架的人少繞一點路 ## 第一次啟動就噴錯 之前工作上有個 LangGraph 寫的 agent 專案要部署，我原本想說照官方文件把 `langgraph-api` 的 Docker image 跑起來就收工 結果一啟動就看到這個 ```text ValueError: License verification failed. Please ensure proper configuration: - For local development, set a valid LANGSMITH_API_KEY for an account with LangGraph Cloud access ... - For production, configure the LANGGRAPH_CLOUD_LICENSE_KEY environment variable with your LangGraph Cloud license key. ``` 當下的反應是：太狠了，想撈錢 ~結果那次其實是我 `DATABASE_URI` 沒設定，錯誤訊息完全誤導人~ 但追下去發現，要 key 這件事是真的 ## LangGraph 其實是兩個東西 平常講 LangGraph，其實混了兩個授權完全不同的東西 | | 授權 | 要不要 key | |---|---|---| | `langgraph` 函式庫，寫 graph、node、checkpointer 的那層 | [MIT](https://github.com/langchain-ai/langgraph/blob/main/LICENSE) | 不用 | | `langgraph-api` 伺服器，`langgraph up` 跑的就是它，提供 assistants、threads、runs、串流這些 API | [Elastic License 2.0](https://pypi.org/project/langgraph-api/) | 要 | 函式庫隨便用，卡住的是伺服器 我把 [`langchain/langgraphjs-api`](https://hub.docker.com/r/langchain/langgraphjs-api) 的 image 挖開來看，裡面寫的是 Elastic License 2.0，PyPI 上的 [`langgraph-api`](https://pypi.org/project/langgraph-api/) 也是 [ELv2](https://www.elastic.co/licensing/elastic-license) 不是 [OSI 認可](https://opensource.org/licenses)的開源授權，有兩條很關鍵（白話版可以看 Elastic 自己的 [FAQ](https://www.elastic.co/licensing/elastic-license/faq)） - 不能把它當託管服務提供給第三方 - 不能繞過授權金鑰的功能 伺服器在 lifespan 階段就會去 `beacon.langchain.com` 驗 key，官方的 [standalone server 文件](https://docs.langchain.com/langsmith/deploy-standalone-server)也寫得很清楚 開發可以用 LangSmith 帳號的 `LANGSMITH_API_KEY`，正式環境要的是 `LANGGRAPH_CLOUD_LICENSE_KEY`，也就是 LangSmith 企業版[自架方案](https://docs.langchain.com/langsmith/self-hosted)，[價格](https://www.langchain.com/pricing)要找業務談 第一次看到這樣保護商業利益的 (?!) ## 多包一層就好了吧？ 我一開始想說，那對外不要直接暴露 `langgraph-api`，前面再包一層自己的 API 應該就可以了吧 啊等等，不對 問題不在誰對外，是這個伺服器沒有 key 根本不會啟動，包幾層都一樣 所以其實只有兩條路 1. 付錢，用 LangSmith 託管或企業自架 2. 只用 MIT 的函式庫，伺服器那層自己來 第二條的代價很大，assistants、threads、runs 那套 API，加上串流、斷線重連、checkpoint 持久化，通通要自己寫 前端如果已經用了 LangGraph SDK，API 格式還得維持一樣 ## Aegra：有人已經寫好了 找開源替代方案時找到 [Aegra](https://github.com/aegra/aegra) [Apache 2.0](https://github.com/aegra/aegra/blob/main/LICENSE)，自己實作了一份跟 LangGraph Platform 相容的伺服器，後面接 PostgreSQL，支援哪些 API 可以看它的 [feature support](https://docs.aegra.dev/feature-support) 我在意的幾點它都有 - 前端的 LangGraph SDK 不用改 - 不用任何 key，也不會連回 LangChain - graph 的程式碼照舊，底層還是 MIT 的 `langgraph` 我先試跑覺得可行，後來跟同事一起把它接進專案 ## 換過去要注意的 相容不等於行為一模一樣，接上真的流量才會發現官方伺服器默默幫你處理掉的事 **閒置時沒有 heartbeat** 上線後開始出現 stream timeout 拿 `langgraph-api` 跟 Aegra 的串流比對，發現官方伺服器在 graph 跑很久、暫時沒輸出的時候，會一直送 heartbeat 讓連線活著 agent 很常有這種空檔，一個 node 在等 LLM 或外部工具，幾十秒沒有新事件很正常 中間只要經過有 idle timeout 的 proxy 或 load balancer，SSE 連線就會被當成閒置切掉 如果你也要換，第一個先測「長時間沒輸出」，不要只測回很快的 demo **每個事件都寫一次資料庫** 為了斷線後能補回漏掉的事件，串流時每個事件除了丟進記憶體的 queue，還會同步寫進 Postgres 可靠是可靠，但事件一多串流就變慢 要改非同步寫、還是換別的儲存，這種取捨自架就得自己扛 **trace 要自己接** 用 LangSmith 的時候 trace 是內建的，自架之後就沒了 我們接了 Sentry 的 [LangGraph 整合](https://docs.sentry.io/platforms/python/integrations/langgraph/)來看錯誤跟每個 node 的執行狀況，Aegra 本身也能把 trace [送到 Langfuse、Phoenix 或任何 OTLP 後端](https://docs.aegra.dev/guides/observability) 這個建議一開始就接，不然出事的時候根本不知道 agent 走到哪一步 ## 心得 重來一次我還是會選 Aegra 但有幾件事會更早想清楚 - 選型時就分清楚函式庫跟伺服器的授權，「LangGraph 是開源的」只對了一半，PoC 用 `langgraph dev` 很順，要上線才撞牆最痛 - 相容層要用自己的情境測，長時間閒置、斷線重連、大量事件才是會出事的地方 - Aegra 預設綁 Postgres，想之後部署得更輕量的話，checkpointer 跟 store 那層會是最難拆的 LangChain 想靠伺服器收錢我覺得合理，總要有人付錢 只是對想把資料、流量、成本都留在自己手上的團隊，知道有 Aegra 這個選項可以少走很多冤枉路 > p.s. 寫這篇時（2026/10）LangChain 官方的說法還是一樣：`langgraph dev` / `langgraph up` [只給開發測試用](https://docs.langchain.com/langsmith/local-server)，正式自架要企業授權，論壇上也有[維護者這樣回覆](https://forum.langchain.com/t/question-about-the-license/2242) ## 參考資料 - [langgraph LICENSE (MIT)](https://github.com/langchain-ai/langgraph/blob/main/LICENSE) - [langgraph-api on PyPI (Elastic License 2.0)](https://pypi.org/project/langgraph-api/) - [Elastic License 2.0](https://www.elastic.co/licensing/elastic-license)、[FAQ](https://www.elastic.co/licensing/elastic-license/faq) - [LangSmith: Deploy a standalone server](https://docs.langchain.com/langsmith/deploy-standalone-server) - [LangSmith: Self-hosted](https://docs.langchain.com/langsmith/self-hosted) - [LangSmith: Local server](https://docs.langchain.com/langsmith/local-server) - [LangChain Forum: Question about the license](https://forum.langchain.com/t/question-about-the-license/2242) - [Aegra](https://github.com/aegra/aegra)、[文件](https://docs.aegra.dev/feature-support) - [Sentry LangGraph integration](https://docs.sentry.io/platforms/python/integrations/langgraph/) --- ## About the author **Ying Xiang Zhao** (geminixiang) — DevOps Engineer, Taipei, Taiwan. Ying Xiang Zhao（geminixiang）是住在台北的 DevOps 工程師，工作橫跨雲原生基礎設施、CI/CD、ML 模型部署與全端開發。這個部落格記錄 infra、資安與 AI coding agent 的實戰筆記；作品包含開源專案 mikan（把 AI coding agent 帶進 Slack / Telegram / Discord）與 tiny-agent（用四種語言實作的極簡 coding agent），瀏覽器內的影片編輯器 Studio，並經營旅遊分帳工具 SentriPay。 **Open to work** — DevOps Engineer / Platform Engineer / Site Reliability Engineer / AI Infrastructure Engineer · Taipei, Taiwan / Remote. Résumé: https://geminixiang.com/about/ (JSON: https://geminixiang.com/resume.json) Topics: DevOps, Cloud Native, Kubernetes, Docker, Terraform, Google Cloud, CI/CD, Security, AI coding agents, ML model deployment, TypeScript, Python Projects: - [mikan](https://github.com/geminixiang/mikan) — Self-hosted AI coding agent for Slack, Telegram, Discord and GitHub with per-conversation sandboxes - [tiny-agent](https://github.com/geminixiang/tiny-agent) — Minimal AI coding agents in TypeScript, Go, Python and Rust, plus a book on how they work - [SentriPay](https://sentripay.com) — Travel expense splitter with multi-currency conversion and shareable, live-synced trip ledgers - [Studio](https://studio.geminixiang.com) — Browser-based video editor built on WebCodecs [About](https://geminixiang.com/about/) · [Résumé](https://geminixiang.com/about/) · [LinkedIn](https://linkedin.com/in/geminixiang/) · [GitHub](https://github.com/geminixiang) · [Twitter](https://x.com/geminixiang)