docs: Agent Framework 技术选型与架构设计

[badadal]

内容

对 8 个 Agent 框架进行 系统分析，给出针对 TRPG AI DM 项目的技术选型推荐。

分析的框架

• PydanticAI — 结构化 Agent SDK
• LangGraph — 状态机工作流引擎
• PydanticAI + LangGraph — 组合方案
• LangChain — 全栈 LLM 框架
• Mastra — TypeScript 工作流框架
• CrewAI — 多 Agent 协作
• AutoGen — 多 Agent 对话
• OpenAI Agents SDK — 轻量 Agent SDK

核心结论

• 全栈统一使用 PydanticAI — Agent共用一个框架
• MVP 不需要编排框架 — Game Loop 是 20 行的 async function，不引入 LangGraph
• 中期可选引入 LangGraph — 当编排复杂度超过阈值时再引入
• 不推荐 LangChain、CrewAI、AutoGen、OpenAI Agents SDK、Mastra

同时覆盖了两个 Agent 系统的框架分析

• Module Parser Agent（离线）：PydanticAI ✅
• Runtime Keeper Agent（在线）：PydanticAI MVP ✅ → +LangGraph 中期可选

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[fennoai]

I found a few documentation accuracy issues that would mislead implementation if this design doc is used as a build guide.

[fennoai]

This document declares agent-module-design.md, 数据模型设计.md, and COC_ENGINE_RULE_REQUIREMENTS.md as prerequisites, and later also relies on agent-implementation-team-plan.md, but none of those files are present in this repository or this PR. A reader cannot verify the architecture assumptions, A/B/C/D mechanism, or schema references this document builds on. Please include/link the prerequisite docs, or remove the hard dependency and inline the required assumptions here.

[fennoai]

The current PydanticAI API documents structured outputs as Agent(..., output_type=ActionPlan), not result_type=... (see https://pydantic.dev/docs/ai/core-concepts/output/). This same result_type pattern appears throughout the document and in the dependency section, so implementers following the snippets against current pydantic-ai will hit stale API examples. Please update the examples/text to output_type or pin and document an older PydanticAI version that still supports result_type.

[fennoai]

This example uses await inside a plain def, so the code block is syntactically invalid as written. Since this is presented as the LangGraph integration pattern, the node functions that await planner.run(...)/narrator.run(...) should be declared async def or rewritten to avoid await.

[fennoai]

This claim is inaccurate for the OpenAI Agents SDK: it supports structured outputs through Agent(output_type=...) with Pydantic models (see https://openai.github.io/openai-agents-python/agents/). If the recommendation is still to avoid the SDK, the comparison should focus on the remaining concerns such as provider coupling and workflow/handoff semantics, not on missing structured-output support.