Agent Architecture Analysis — 代理 Architecture Analysis

12-Factor 代理s 合规 Analysis

Reference: 12-Factor 代理s

输入 Parameters Parameter Description Required docs_path Path to documentation directory (for existing analyses) Optional codebase_path Root path of the codebase to analyze Required Analysis 框架 Factor 1: Natural Language to 工具 Calls

Principle: Convert natural language 输入s into structured, deterministic 工具 calls using 模式-验证d 输出s.

搜索 Patterns:

# Look for Pydantic 模式s grep -r "class.Base模型" --include=".py" grep -r "TaskDAG\|Task响应\|工具Call" --include=".py"

# Look for JSON 模式 generation grep -r "模型_json_模式\|json_模式" --include=".py"

# Look for structured 输出 generation grep -r "输出_type\|响应_模型" --include=".py"

File Patterns: /代理s/.py, */模式s/.py, */模型s/.py

合规 Criteria:

Level Criteria Strong All LLM 输出s use Pydantic/dataclass 模式s with 验证器s Partial Some 输出s typed, but dict returns or un验证d strings exist Weak LLM returns raw strings 解析d manually or with regex

Anti-patterns:

json.loads(llm_响应) without 模式 验证 输出.split() or regex parsing of LLM 响应s dict[str, Any] return types from 代理s No 验证 between LLM 输出 and 处理器 execution Factor 2: Own Your Prompts

Principle: Treat prompts as first-class code you control, version, and iterate on.

搜索 Patterns:

# Look for embedded prompts grep -r "系统_PROMPT\|系统_prompt" --include=".py" grep -r '""".You are' --include=".py"

# Look for template 系统s grep -r "jinja\|Jinja\|render_template" --include=".py" find . -name ".jinja2" -o -name ".j2"

# Look for prompt directories find . -type d -name "prompts"

File Patterns: /prompts/, /templates/, */代理s/.py

合规 Criteria:

Level Criteria Strong Prompts in separate files, templated (Jinja2), versioned Partial Prompts as 模块 constants, some parameterization Weak Prompts hardcoded inline in functions, f-strings only

Anti-patterns:

f"You are a {角色}..." inline in 代理 methods Prompts mixed with business 记录ic No way to iterate on prompts without code changes No prompt versioning or A/B 测试 capability Factor 3: Own Your 上下文 Window

Principle: Control how 历史, 状态, and 工具 结果s are 格式化ted for the LLM.

搜索 Patterns:

# Look for 上下文/message management grep -r "代理Message\|ChatMessage\|messages" --include=".py" grep -r "上下文_window\|上下文_编译器" --include=".py"

# Look for custom serialization grep -r "to_xml\|to_上下文\|序列化" --include=".py"

# Look for 令牌 management grep -r "令牌_count\|max_令牌s\|t运行cate" --include=".py"

File Patterns: */上下文/.py, */状态/.py, */core/.py

合规 Criteria:

Level Criteria Strong Custom 上下文 格式化, 令牌 optimization, typed 事件, compaction Partial Basic message 历史 with some structure Weak Raw message accumulation, standard OpenAI 格式化 only

Anti-patterns:

Unbounded message accumulation Large artifacts embedded inline (diffs, files) No 代理-specific 上下文 过滤器ing Same 上下文 for all 代理 types Factor 4: 工具s Are Structured 输出s

Principle: 工具s produce 模式-验证d JSON that triggers deterministic code, not magic function calls.

搜索 Patterns:

# Look for 工具/响应 模式s grep -r "class.响应.Base模型" --include=".py" grep -r "工具结果\|工具输出" --include=".py"

# Look for deterministic 处理器s grep -r "def handle_\|def 执行_" --include=".py"

# Look for 验证 layer grep -r "模型_验证\|解析_obj" --include=".py"

File Patterns: */工具s/.py, */处理器s/.py, */代理s/.py

合规 Criteria:

Level Criteria Strong All 工具 输出s 模式-验证d, 处理器s type-safe Partial Most 工具s typed, some loose dict returns Weak 工具s return arbitrary dicts, no 验证 layer

Anti-patterns:

工具 处理器s that directly 执行 LLM 输出 eval() or exec() on LLM-生成d code No separation between decision (LLM) and execution (code) Magic method dis补丁 based on string matching Factor 5: Unify Execution 状态

Principle: Merge execution 状态 (step, retries) with business 状态 (messages, 结果s).

搜索 Patterns:

# Look for 状态 模型s grep -r "Execution状态\|工作流状态\|Thread" --include=".py"

# Look for dual 状态 系统s grep -r "检查point\|MemorySaver" --include=".py" grep -r "sqlite\|database\|仓库" --include=".py"

# Look for 状态 reconstruction grep -r "load_状态\|恢复\|reconstruct" --include=".py"

File Patterns: */状态/.py, */模型s/.py, */database/.py

合规 Criteria:

Level Criteria Strong Single serializable 状态 object with all execution metadata Partial 状态 exists but split across 系统s (memory + DB) Weak Execution 状态 scattered, requires multiple queries to reconstruct

Anti-patterns:

Retry count stored separately from task 状态 Error 历史 in 记录s but not in 状态 LangGraph 检查points + separate database storage