用 AI Agent 处理复杂流程：先写 Workflow，再写 Prompt

{
  "protocol": "a2a.v1",
  "id": "msg_20260206_000123",
  "correlation_id": "run_20260206_210000",
  "sender": "SuperAgent",
  "receiver": "ResearchAgent",
  "intent": "collect_references",
  "input": {
    "topic": "ai agent workflow",
    "constraints": {
      "language": "zh-CN",
      "no_bare_url": true
    }
  },
  "status": "ok",
  "output": {
    "references": [
      {
        "title": "Model Context Protocol - Specification",
        "url": "https://modelcontextprotocol.io/specification/latest",
        "notes": "MCP 规范入口，包含 lifecycle、tools、resources、prompts 等"
      }
    ]
  },
  "artifact": [
    { "type": "markdown", "path": "content/journal/xxx.md" }
  ],
  "error": null,
  "metrics": { "latency_ms": 812, "tokens_in": 1200, "tokens_out": 350 }
}

prompts/
  super/
    router.v1.md
    evaluator.v1.md
  agents/
    research/
      system.v1.md
      user_template.v1.md
    coder/
      system.v1.md
      user_template.v1.md
    writer/
      system.v1.md
      outline.v1.md
      draft.v1.md
schemas/
  a2a/
    message.v1.json
workflows/
  blog_write.v1.yaml
  audit_report.v1.yaml

@startuml
skinparam componentStyle rectangle
skinparam shadowing false
skinparam rectangleBorderColor #555555

rectangle "Super Agent\n(Orchestrator)" as SA #FFD700
rectangle "Workflow Definition\n(DAG / State Machine)" as WF #FFEEBB

rectangle "SubAgents" as SUB #E8F5E9 {
  rectangle "ResearchAgent\n(SRP: references)" as RA #C8E6C9
  rectangle "CodeAgent\n(SRP: changes/tests)" as CA #C8E6C9
  rectangle "DocAgent\n(SRP: writing)" as DA #C8E6C9
  rectangle "DiagramAgent\n(SRP: render)" as GA #C8E6C9
}

rectangle "A2A Message Contract\n(schema + version)" as A2A #E3F2FD
rectangle "Prompt Repo\n(files + git)" as PR #E3F2FD

rectangle "MCP Servers\n(tools/resources/prompts)" as MCP #F3E5F5
rectangle "Workspace\n(files/artifacts)" as WS #FFF3E0

SA --> WF : design + execute
SA --> A2A : enforce contract
SA --> PR : load prompts
SA --> RA : dispatch tasks
SA --> CA
SA --> DA
SA --> GA

RA --> MCP : search/tools
CA --> MCP : git/build/tools
DA --> PR : templates
GA --> WS : images

MCP --> WS : read/write (scoped)
@enduml

@startuml
autonumber
skinparam participantBackgroundColor #FAFAFA
skinparam participantBorderColor #555555
participant "SuperAgent\n(Orchestrator)" as SA #FFD700
participant "ResearchAgent" as RA #C8E6C9
participant "DocAgent" as DA #C8E6C9
participant "DiagramAgent" as GA #C8E6C9
participant "MCP Server" as MCP #F3E5F5
participant "Workspace" as WS #FFF3E0

SA -> RA : A2A(request)\nintent=collect_references\nschema=a2a.v1
RA -> MCP : tool.search(query)
MCP --> RA : results (structured)
RA --> SA : A2A(response)\nreferences[] + confidence

SA -> DA : A2A(request)\nintent=draft_article\ninput=notes+refs
DA --> SA : A2A(response)\nmarkdown_draft

SA -> GA : A2A(request)\nintent=render_diagrams\ninput=code_blocks
GA -> WS : write images
GA --> SA : A2A(response)\nimages[]

SA -> MCP : tool.verify_links(urls)
MCP --> SA : ok / broken[]

SA -> WS : write final markdown
@enduml

@startuml
skinparam shadowing false
skinparam activityBackgroundColor #f5f5f5
skinparam activityBorderColor #555555

(*) --> "==Supervisor==\n(论文主编)" #FFD700
"==Supervisor==\n(论文主编)" --> "LiteratureAgent\nPubMed 文献检索" #C8E6C9
"LiteratureAgent\nPubMed 文献检索" --> "==Supervisor==\n(论文主编)"

"==Supervisor==\n(论文主编)" --> "StatsAgent\n统计分析" #BBDEFB
"StatsAgent\n统计分析" --> "==Supervisor==\n(论文主编)"

"==Supervisor==\n(论文主编)" --> "WriterAgent\nIMRAD 撰写" #FFE0B2
"WriterAgent\nIMRAD 撰写" --> "==Supervisor==\n(论文主编)"

"==Supervisor==\n(论文主编)" --> "ComplianceAgent\nCONSORT 合规审查" #E1BEE7
"ComplianceAgent\nCONSORT 合规审查" --> "==Supervisor==\n(论文主编)"

"==Supervisor==\n(论文主编)" --> "END\n输出终稿" #F5F5F5
@enduml

"""
clinical_paper_workflow.py
用 LangGraph 实现临床医学论文多 Agent 写作工作流

场景：写一篇 RCT（随机对照试验）论文，比较两种降压药的疗效
流程：文献检索 -> 统计分析 -> IMRAD 撰写 -> CONSORT 合规审查

概念映射：
  Super Agent   -> supervisor（通讯作者 / 论文主编）
  SubAgent(SRP) -> literature / stats / writer / compliance
  A2A 通讯      -> MessagesState（结构化消息链）
  Workflow      -> StateGraph（声明式 DAG）
"""

from langgraph.prebuilt import create_react_agent
from langgraph.graph import StateGraph, START, END, MessagesState
from langchain_core.tools import tool


# =========================================================
# 1. 定义每个 SubAgent 的专属 Tools
# =========================================================

@tool
def search_pubmed(query: str, max_results: int = 5) -> str:
    """Search PubMed for clinical research papers."""
    # 真实场景接 NCBI E-utilities API 或 MCP PubMed server
    return (
        f"[PubMed results for '{query}', top {max_results}]\n"
        "1. PMID:38901234 - 'Amlodipine vs Losartan in Stage 2 HTN: "
        "A 12-month RCT' (Lancet 2025) - N=480, primary: 24h-ABPM\n"
        "2. PMID:38876543 - 'Meta-analysis of CCB vs ARB in elderly HTN' "
        "(BMJ 2024) - 12 RCTs, N=8,320\n"
        "3. PMID:38765432 - 'CONSORT 2025 updated checklist for RCTs' "
        "(Ann Intern Med 2025)\n"
        "4. PMID:38654321 - 'Renal outcomes in ARB-treated diabetic HTN' "
        "(NEJM 2024) - N=1,200\n"
        "5. PMID:38543210 - 'Adverse events profiling: CCB vs ARB classes' "
        "(Pharmacotherapy 2025) - systematic review"
    )

@tool
def run_stats_analysis(design: str, groups: str, endpoint: str) -> str:
    """Run statistical analysis on clinical trial data."""
    # 真实场景接 R/Python stats 脚本，或 MCP 数据分析 server
    return (
        f"[Statistical Report: {design}]\n"
        f"Groups: {groups}\n"
        f"Primary endpoint: {endpoint}\n\n"
        "Results:\n"
        "- Amlodipine group (n=240): mean SBP reduction 18.3 mmHg (SD 6.2)\n"
        "- Losartan group (n=240): mean SBP reduction 16.7 mmHg (SD 5.8)\n"
        "- Between-group diff: 1.6 mmHg (95% CI: 0.5-2.7, p=0.012)\n"
        "- NNT for target BP (<130/80): 14\n"
        "- Adverse events: peripheral edema 12.1% vs 3.3% (p<0.001)\n"
        "- Kaplan-Meier 12-month adherence: 82% vs 89% (log-rank p=0.04)\n"
        "- Sensitivity analysis (per-protocol): consistent with ITT"
    )

@tool
def write_imrad_section(section: str, data: str) -> str:
    """Write a section of the paper in IMRAD format."""
    # 真实场景用更强的模型 + 领域 prompt 模板
    templates = {
        "introduction": (
            "## Introduction\n\n"
            "Hypertension affects over 1.28 billion adults worldwide (WHO 2023). "
            "Current guidelines recommend CCBs and ARBs as first-line agents, "
            "yet head-to-head RCTs comparing amlodipine and losartan remain scarce...\n"
            f"(Based on literature: {data[:100]}...)"
        ),
        "methods": (
            "## Methods\n\n"
            "### Study design\n"
            "Prospective, randomized, double-blind, active-controlled trial.\n"
            "### Participants\n"
            "Adults 40-75 y with stage 2 HTN (SBP 140-179 mmHg). "
            "Key exclusion: secondary HTN, eGFR <30.\n"
            "### Randomization\n"
            "1:1 allocation via computer-generated sequence, "
            "stratified by diabetes status.\n"
            f"(Stats plan: {data[:80]}...)"
        ),
        "results": (
            "## Results\n\n"
            f"{data}\n\n"
            "Figure 1: Kaplan-Meier adherence curves.\n"
            "Table 1: Baseline characteristics (well-balanced, p>0.05 for all)."
        ),
        "discussion": (
            "## Discussion\n\n"
            "Our findings suggest a statistically significant but clinically modest "
            "advantage of amlodipine over losartan in 24h SBP reduction. "
            "However, the higher edema rate and lower adherence in the amlodipine "
            "group warrant individualized treatment decisions...\n"
            f"(Contextualized with: {data[:80]}...)"
        ),
    }
    return templates.get(section.lower(), f"## {section}\n\n{data}")

@tool
def check_consort_compliance(manuscript: str) -> str:
    """Check manuscript against CONSORT 2025 checklist."""
    # 真实场景：逐条比对 CONSORT 25 项 + 流程图
    return (
        "CONSORT 2025 Compliance Report:\n\n"
        "PASS [1] Title: identified as randomised trial\n"
        "PASS [2] Abstract: structured, includes key numbers\n"
        "PASS [3a] Background: scientific rationale stated\n"
        "WARN [6a] Outcomes: secondary endpoints not fully pre-specified\n"
        "PASS [7a] Sample size: calculation provided (power=0.80, alpha=0.05)\n"
        "PASS [8a] Randomization: sequence generation described\n"
        "WARN [11a] Blinding: assessor blinding not explicitly confirmed\n"
        "PASS [13a] Flow diagram: CONSORT flow present\n"
        "PASS [16] Ancillary analyses: sensitivity analysis included\n"
        "FAIL [23] Registration: trial registry number missing\n\n"
        "Score: 22/25 items PASS, 2 WARN, 1 FAIL\n"
        "Action required: add trial registration number (e.g. NCT0xxxxxxx)"
    )


# =========================================================
# 2. 定义四个 SubAgent（SRP：一个 Agent 只干一件事）
# =========================================================

literature_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[search_pubmed],
    prompt=(
        "你是 LiteratureAgent，只负责在 PubMed 检索相关临床文献。"
        "输出结构化的参考列表：PMID、标题、期刊、年份、样本量、关键结论。"
        "不要写论文正文，不要做统计分析。"
    ),
    name="literature_agent",
)

stats_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[run_stats_analysis],
    prompt=(
        "你是 StatsAgent，只负责对临床试验数据做统计分析。"
        "输出：主要终点结果、p 值、置信区间、效应量、敏感性分析。"
        "不要写论文正文，不要检索文献。"
    ),
    name="stats_agent",
)

writer_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[write_imrad_section],
    prompt=(
        "你是 WriterAgent，根据文献和统计结果撰写论文。"
        "严格使用 IMRAD 结构（Introduction, Methods, Results, Discussion）。"
        "学术语言，客观严谨，引用须标注 PMID。"
        "不要自己编造数据，只用已有的文献和统计结果。"
    ),
    name="writer_agent",
)

compliance_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[check_consort_compliance],
    prompt=(
        "你是 ComplianceAgent，按 CONSORT 2025 清单审查论文手稿。"
        "逐条检查并输出：PASS / WARN / FAIL + 具体修改建议。"
        "不要自己改写论文，只输出审查报告。"
    ),
    name="compliance_agent",
)


# =========================================================
# 3. 定义 Supervisor（通讯作者：编排 + 质控）
# =========================================================

supervisor_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[],  # supervisor 不需要 tools，它靠路由决策
    prompt=(
        "你是 Supervisor（通讯作者），管理四个 Agent：\n"
        "1. literature_agent - 负责 PubMed 文献检索\n"
        "2. stats_agent - 负责统计分析\n"
        "3. writer_agent - 负责 IMRAD 论文撰写\n"
        "4. compliance_agent - 负责 CONSORT 合规审查\n\n"
        "标准流程：\n"
        "  Step 1: literature_agent 检索相关 RCT 和 meta-analysis\n"
        "  Step 2: stats_agent 分析试验数据\n"
        "  Step 3: writer_agent 按 IMRAD 撰写各章节\n"
        "  Step 4: compliance_agent 做 CONSORT 合规检查\n\n"
        "每次只分派一个任务。如果合规审查有 FAIL 项，"
        "把修改意见转给 writer_agent 修订，然后重新审查。\n"
        "全部 PASS 或仅剩 WARN 后，输出最终结论并结束。"
    ),
    name="supervisor",
)


# =========================================================
# 4. 组装 StateGraph -- 声明式 workflow
# =========================================================

workflow = (
    StateGraph(MessagesState)
    .add_node(
        supervisor_agent,
        destinations=(
            "literature_agent", "stats_agent",
            "writer_agent", "compliance_agent", END
        ),
    )
    .add_node(literature_agent)
    .add_node(stats_agent)
    .add_node(writer_agent)
    .add_node(compliance_agent)
    .add_edge(START, "supervisor")
    # 每个 SubAgent 完成后回到 supervisor
    .add_edge("literature_agent", "supervisor")
    .add_edge("stats_agent", "supervisor")
    .add_edge("writer_agent", "supervisor")
    .add_edge("compliance_agent", "supervisor")
    .compile()
)


# =========================================================
# 5. 执行 -- 一句话触发整个论文写作流程
# =========================================================

if __name__ == "__main__":
    result = workflow.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "请帮我写一篇 RCT 论文：比较氨氯地平与氯沙坦"
                        "治疗 2 期高血压的 12 个月疗效和安全性。"
                        "样本量 480 例，主要终点为 24 小时动态血压。"
                    ),
                }
            ]
        }
    )
    for msg in result["messages"]:
        role = getattr(msg, "type", "unknown")
        content = getattr(msg, "content", "")
        if content:
            print(f"[{role}] {content[:200]}")
            print("---")

from typing import List, Optional

class ClinicalPaperState(MessagesState):
    """扩展 state，让论文写作的 A2A 数据更结构化"""
    references: List[dict]         # LiteratureAgent: PMID + 摘要
    stats_report: str              # StatsAgent: 统计分析报告
    manuscript_sections: dict      # WriterAgent: {"intro": ..., "methods": ...}
    consort_score: Optional[dict]  # ComplianceAgent: {pass: 22, warn: 2, fail: 1}
    revision_round: int            # 第几轮修订（可观测性）

from pathlib import Path

def load_prompt(agent_name: str, version: str = "v1") -> str:
    """从 prompts/ 目录加载对应版本的 system prompt"""
    path = Path(f"prompts/agents/{agent_name}/system.{version}.md")
    return path.read_text(encoding="utf-8")

# 用法：升级 CONSORT 检查清单时，只需要改 compliance 的 prompt 文件
compliance_agent = create_react_agent(
    model="openai:gpt-4o-mini",
    tools=[check_consort_compliance],
    prompt=load_prompt("compliance", "v2"),  # CONSORT 2025 版
    name="compliance_agent",
)

from mcp import ClientSession

@tool
async def mcp_pubmed_search(query: str, max_results: int = 5) -> str:
    """通过 MCP Server 检索 PubMed（替代直接调 NCBI API）"""
    async with ClientSession(transport) as session:
        result = await session.call_tool(
            "pubmed_search",
            arguments={"query": query, "max_results": max_results}
        )
        return result.content[0].text

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #FAFAFA
  }
  :depth(0) {
    BackgroundColor #FFD700
  }
  :depth(1) {
    BackgroundColor #E3F2FD
  }
  :depth(2) {
    BackgroundColor #F5F5F5
  }
}
</style>
* 用 AI Agent 处理复杂流程
** 先定义角色
*** Super Agent
**** 识别/拆分任务
**** 编排 workflow（顺序/并行/重试）
**** 汇总成果 + 验收一致性
*** SubAgent（SRP）
**** Research：资料与引用
**** Code：改动与测试
**** Doc：写作与结构化输出
**** Diagram：渲染与产物管理
** SOLID 设计原则
*** SRP：一个 Agent 一个职责
*** OCP：加能力 = 加节点/加文件
*** LSP：遵守契约即可互换
*** ISP：最小够用的工具集
*** DIP：依赖契约，不依赖实现
** A2A：结构化通讯
*** schema + version
*** correlation_id 可追踪
*** error 分类 + 策略化重试
** Prompt：文件化版本管理
*** prompts/ 目录
*** Git diff/review/rollback
** Workflow：先设计再执行
*** DAG/状态机
*** 超时/重试/兜底写在执行层
** MCP：工具接入标准化
*** tools/resources/prompts
*** 权限边界更清晰
** LangGraph 实战
*** Supervisor + SubAgent
*** MessagesState = A2A
*** @tool + MCP 适配
** 观测与安全
*** 日志脱敏
*** 最小权限
*** 产物可审计
@endmindmap