医疗AI Agent执行层：从自然语言到X12 270/271资格查询实务

在实际医疗场景里AI Agent 的价值不在于能生成一段像模像样的自然语言回复而在于它生成的结果能被医院、保险公司、清算所和 EHR 系统真实接收并处理。换句话说Agent 的“执行层”必须先解决合规和互操作问题。对医疗数据交换来说这个执行层的底层约束就是 X12 标准。这篇文章会从一个最小可运行的医疗资格查询 Agent 入手解释为什么 X12 不是一堆已经过时的 EDI 报文字段而是决定 Agent 输出是否可落地的关键契约。你会看到完整的 270/271 交易集生成、发送、接收和解析过程也会看到 Agent 在提取意图、生成报文、处理响应时最容易踩的坑。学完之后你能把同样的思路迁移到 837 理赔、835 付款通知、278 转诊授权等更多 X12 交易集上。1. 先理解医疗 AI Agent 为什么必须面对执行层问题1.1 自然语言生成结果不等于可执行结果大多数 AI Agent demo 停留在“用户问一句Agent 答一段”的阶段。但在医疗领域一段自然语言答案不能直接被保险公司或清算所接受也不能自动进入 EHR 的预约、理赔、授权流程。医疗信息系统之间交换的是结构化数据而结构化数据必须符合行业标准。这个标准就是 X12它规定了报文由哪些段构成、段的顺序、字段长度、枚举值、日期格式、层级关系以及交易对手之间如何确认收到。如果把 Agent 的输出直接丢给下游系统会引发三类问题。第一语义不完整系统不知道这笔请求是查资格、提交理赔还是查授权。第二结构不对即使内容是 270 资格查询段的顺序或嵌套错误也会被网关拒绝。第三字段不规范比如日期不是 CCYYMMDD 格式、诊断码不是 ICD-10、服务类型代码不在枚举范围内。这些问题都不是“优化提示词”能解决的需要在 Agent 架构中增加一个懂 X12 的执行模块。1.2 执行层在 Agent 架构里承担什么职责一个医疗 Agent 的典型流程是接收用户输入调用 LLM 做意图识别和实体抽取形成结构化请求然后调用后端系统完成实际动作。这个过程中执行层负责把结构化请求转换为外部系统能接受的协议并处理返回值。对医疗 AI Agent 而言执行层至少要包含三块能力交易集映射把 Agent 识别出的业务语义映射到 X12 交易集的段和元素上。报文生成与解析生成符合语法规则的 EDI 文本解析来自交易所或保险公司的响应。校验与审计在发送前检查必填项、枚举值、长度和循环嵌套在接收后保留原始报文用于审计和回溯。如果缺少这个执行层Agent 只是一个“会聊天的高智商客服”有了它Agent 才真正具备“替用户办理业务”的能力。这也是 X12 在医疗 Agent 项目中被称为关键约束的原因约束不是限制而是保证结果可落地的必要条件。2. X12 的语法和核心交易集是执行层绕不开的基线2.1 EDI 文本的层次结构段、元素、循环X12 EDI 报文本质是纯文本它依靠分隔符和段层级来表达业务含义。一个完整报文从外到内是ISA/IEA 控制层整个交换信封包含发送方、接收方、控制号、日期时间。GS/GE 功能组层一组同类型交易集的集合包含功能组编码。ST/SE 交易集层一个具体交易集比如 270 或 837包含交易集控制号。业务段每个段以两到三个字母的段标识开头如 NM1 表示姓名、EQ 表示服务类型。数据元素段内用元素分隔符分开的字段。复合元素用复合元素分隔符分开的子字段常见于 DTP、REF 等段。ISA 段是定长的比如发送方 ID 必须占 15 位不够补空格。GS 和 ST 层则是变长的只靠元素分隔符区分字段。这种混用规则是新手容易出错的地方。2.2 医疗服务中最常见的 X12 交易集医疗领域不是只有一个 X12 报文而是按业务场景分成多个交易集。理解它们之间的关系有助于 Agent 在执行层做好交易集路由。交易集中文场景业务方向常见用途270/271资格查询与响应请求/响应查询患者保险是否有效、覆盖范围、自付额837医疗理赔提交请求医院或诊所提交费用理赔835付款/汇款通知响应保险公司说明付款金额和原因278转诊授权请求/响应申请或返回转诊授权834保险注册请求批量投保登记820保费支付请求支付保费对于一个 AI Agent 平台通常先接 270/271因为它逻辑相对简单、参与方结构清晰而且对患者和前台运营价值高快速确认保险是否有效、有无自付额、免赔额还剩多少。2.3 为什么 270/271 适合作为 Agent 第一个落地点270/271 交易集的特点是请求和响应一一对应。请求方发出 270接收方返回 271两边都使用相同的 HL 层级结构表达信息提供方、信息接收方和患者。这种对应关系让 Agent 的实现难度集中在“如何正确生成 270”和“如何解析 271”上不涉及复杂的批次对账和状态机。跑通之后再扩展到 837 理赔或 278 授权核心 X12 组件可以复用。3. 搭建一个可本地运行的最小资格查询 Agent3.1 技术选型和环境准备为了让例子可以离线复现这里使用 Python 3.10 FastAPI httpx通过一个模拟 EDI 网关完成 270/271 交换。LLM 部分使用 OpenAI 兼容接口但核心 X12 生成和解析不依赖特定模型。环境要求组件版本/说明Python3.10 或更高FastAPI0.104 或更高uvicorn0.24 或更高httpx0.25 或更高pydantic2.xopenai1.x仅用于调用 LLM操作系统Windows/Linux/macOS 均可安装依赖python -m venv .venv source .venv/bin/activate # Windows 下为 .venv\Scripts\activate pip install fastapi uvicorn[standard] httpx pydantic openai3.2 项目结构medical_x12_agent/ ├── agent_main.py # Agent 主流程FastAPI 接口 ├── x12_builder.py # 生成 270 报文的 X12 构造器 ├── x12_parser.py # 解析 271 报文的 X12 解析器 ├── llm_extract.py # 调用 LLM把自然语言转成结构化请求 ├── mock_edi_server.py # 模拟保险公司 EDI 网关 └── requirements.txt这种分层刻意把 LLM 和 X12 拆开。LLM 负责从自由文本中提取业务意图X12 模块负责把结构化意图变成合法报文。这样即使后续更换模型X12 逻辑也不会被破坏。3.3 模拟 EDI 网关先实现模拟网关方便 Agent 后续发送 270 后能拿到一个固定的 271 响应。# mock_edi_server.py from fastapi import FastAPI, Request from fastapi.responses import PlainTextResponse app FastAPI() SAMPLE_271 ISA*00* *00* *ZZ*RECEIVERID01 *ZZ*SENDERID001 *231101*1200*^*00501*000000002*0*P*:~ GS*HS*RECEIVERID01*SENDERID001*20231101*1200*0001*X*005010X279A1~ ST*271*0001~ BHT*0022*11*10001234*20231101*1200*ET~ HL*1**20*1~ NM1*PR*2*MEDICAID*****PI*RECEIVERID01~ HL*2*1*21*1~ NM1*1P*1*DOE*JOHN****XX*1234567891~ HL*3*2*22*0~ NM1*IL*1*JACKSON*MICHAEL****MI*JACKSONM~ EB*1*D*73***30**DIS$150 COPAY AFTER DED~ REF*6R*2500~ DTP*307*D8*20231115~ SE*11*0001~ GE*1*0001~ IEA*1*000000002~ app.post(/edi/270) async def receive_270(request: Request): raw await request.body() # 实际网关会先做语法校验这里简化为收到合法 270 就返回 271 return PlainTextResponse(SAMPLE_271, media_typetext/plain) if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8001)这个模拟网关没有真正解析收到的 270只用于演示读写流程。实际对接清算所时发送方还要处理认证、批量分包、回执和重试。4. 核心实现从自然语言到 270 报文4.1 用 LLM 提取结构化资格查询意图用户输入可能是“查一下 Michael Jackson 的 Medicaid 是否有效生日是 1980-01-15”也可能是“患者 JACKSONM家庭医生是 John DoeNPI 1234567891”。LLM 需要把这句话映射成三个参与方加一个服务类型。这里用 Pydantic 定义提取结果约束 LLM 输出结构# llm_extract.py from pydantic import BaseModel from openai import OpenAI class EligibilityRequest(BaseModel): provider_last_name: str provider_first_name: str provider_npi: str patient_last_name: str patient_first_name: str patient_member_id: str service_type_code: str 30 def extract_eligibility_request(user_text: str, client: OpenAI) - EligibilityRequest: prompt f 你是医疗前台系统中的保险资格识别助手。 请从用户的自然语言中提取以下信息: - provider_last_name: 服务提供者姓氏 - provider_first_name: 服务提供者名字 - provider_npi: 服务提供者 NPI 编号 - patient_last_name: 患者姓氏 - patient_first_name: 患者名字 - patient_member_id: 患者保险会员号 - service_type_code: 默认 30表示健康计划覆盖 只输出 JSON不要解释。 用户输入: {user_text} resp client.chat.completions.create( modelgpt-4o-mini, response_format{type: json_object}, messages[{role: user, content: prompt}], ) return EligibilityRequest.model_validate_json(resp.choices[0].message.content)之所以不直接让 LLM 输出 X12 文本是因为 LLM 对定长段、控制号和枚举值的记忆不可靠很容易出现字段顺序错误、空格数量不对、枚举值非法等问题。让 LLM 先输出 JSON再由专门模块生成 X12错误率会低很多也更容易做单元测试。4.2 用 X12 构造器生成 270 报文270 请求的核心是把三个参与方放进 HL 循环HL 1信息源即交易接收方例如保险公司。HL 2信息接收方即发起请求的诊所或服务提供者。HL 3患者或会员。这三层通过 HL 的父子关系嵌套然后用 NM1 描述各自姓名和 ID用 EQ 声明服务类型。# x12_builder.py from datetime import datetime from llm_extract import EligibilityRequest INFORMATION_SOURCE_ID RECEIVERID01 INFORMATION_RECEIVER_ID SENDERID001 def build_270(req: EligibilityRequest, control_number: int 1) - str: now datetime.now() date_str now.strftime(%Y%m%d) time_str now.strftime(%H%M) st01 270 st02 0001 isa13 str(control_number).zfill(9) group_no 0001 sender_id INFORMATION_RECEIVER_ID.ljust(15) receiver_id INFORMATION_SOURCE_ID.ljust(15) lines [] lines.append( fISA*00* *00* *ZZ*{sender_id}*ZZ*{receiver_id} f*{date_str}*{time_str}*^*00501*{isa13}*0*P*:~ ) lines.append( fGS*HS*{INFORMATION_RECEIVER_ID}*{INFORMATION_SOURCE_ID} f*{date_str}*{time_str}*{group_no}*X*005010X279A1~ ) lines.append(fST*{st01}*{st02}~) lines.append((fBHT*0022*13*{date_str}{time_str}*{date_str}*{time_str}*ET~)) lines.append(HL*1**20*1~) lines.append(fNM1*PR*2*MEDICAID*****PI*{INFORMATION_SOURCE_ID}~) lines.append(HL*2*1*21*1~) lines.append( fNM1*1P*1*{req.provider_last_name}*{req.provider_first_name} f****XX*{req.provider_npi}~ ) lines.append(HL*3*2*22*0~) lines.append( fNM1*IL*1*{req.patient_last_name}*{req.patient_first_name} f****MI*{req.patient_member_id}~ ) lines.append(fEQ*{req.service_type_code}~) lines.append(fSE*9*0001~) lines.append(fGE*1*0001~) lines.append(fIEA*1*{isa13}~) return \n.join(lines)这段代码最容易出错的地方有三个。第一ISA 段中发送方和接收方 ID 必须补齐 15 位。ljust(15)会把 ID 补空格到 15 位否则定长校验会直接失败。第二NM1 段里使用了****来跳过多余字段。270 中 NM1 的布局是NM1*实体代码*类型*姓*名*中间名*后缀*ID 代码限定符*ID如果中间名和留空就要用空元素占位。第三HL 层的父子关系不能随意改。HL1**201 表示第一层是信息源第 20 号实体类型HL21211 以第一层为父层表示信息接收方HL32220 以第二层为父层表示患者。这里的数字一旦写错接收方解析时会把 NM1 分错角色。4.3 Agent 主流程生成、发送、接收Agent 主流程把 LLM 提取、270 生成、HTTP 发送、271 解析串起来。# agent_main.py from fastapi import FastAPI from pydantic import BaseModel from openai import OpenAI from llm_extract import extract_eligibility_request from x12_builder import build_270 from x12_parser import parse_271 import httpx app FastAPI() client OpenAI() MOCK_EDI_URL http://127.0.0.1:8001/edi/270 class UserInput(BaseModel): text: str class AgentResponse(BaseModel): eligibility_status: str message: str deducible: str copay: str original_271: str app.post(/agent/eligibility, response_modelAgentResponse) async def eligibility(user_input: UserInput): req extract_eligibility_request(user_input.text, client) x12_270 build_270(req) async with httpx.AsyncClient() as http: resp await http.post(MOCK_EDI_URL, contentx12_270, headers{Content-Type: text/plain}) x12_271 resp.text result parse_271(x12_271) return AgentResponse( eligibility_statusresult[status], messageresult[message], deducibleresult[deductible], copayresult[copay], original_271x12_271, ) if __name__ __main__: import uvicorn uvicorn.run(app, host127.0.0.1, port8000)这一步的关键是“Agent 的决策点”。LLM 决定用户意图但真正发出去的动作由 X12 模块执行。架构上不要让 LLM 直接操作网络否则模型异常输出会影响下游。5. 解析 271 响应把 EDI 文本转回业务语义5.1 271 的段结构与关键字段271 响应和 270 请求使用同样的 HL 层级。前三层依然是信息源、信息接收方、患者。但 270 中 EQ 段表示“我想查什么服务”271 中 EB 段表示“该服务的资格状态”EB 后通常跟 REF、DTP 等补充段。一个简化版 271 的关键字段段含义关键元素HL层级1/2/3 层业务角色NM1参与方姓名第 2 个元素PR/1P/ILEB资格或福利信息第 2 个元素资格状态码第 4 个元素覆盖层级REF参考信息第 2 个元素可扣除额第 3 个元素金额DTP日期日期限定符和日期值EB 段的第 2 个元素是资格状态码常用值状态码含义1有效2无效3未确认4已确认但存在限制5.2 用行遍历法解析 271271 解析器不需要完整的 EDI 引擎按行遍历已经能覆盖多数 Agent 场景。# x12_parser.py def parse_271(raw_271: str) - dict: result { status: UNKNOWN, message: , deductible: , copay: , } in_patient_loop False for line in raw_271.splitlines(): line line.rstrip(\n) seg line.split(*) seg_id seg[0] elements [e.replace(~, ) for e in seg] if seg_id HL: hl_code elements[3] if len(elements) 3 else in_patient_loop (hl_code 22) elif seg_id EB and in_patient_loop: status_map {1: ACTIVE, 2: INACTIVE, 3: UNCONFIRMED, 4: RESTRICTED} result[status] status_map.get(elements[1], elements[1]) result[message] elements[6] if len(elements) 6 and elements[6] else elif seg_id REF and in_patient_loop: ref_code elements[1] ref_value elements[2] if len(elements) 2 else if ref_code 6R: result[deductible] ref_value elif ref_code F5: result[copay] ref_value return result上面的代码只解析了 271 的最简结构。真实 271 中EB 段可能有多条一条代表住院覆盖另一条代表门诊覆盖REF 也可能有多条。生产版本应该把多个 EB 段组织成列表而不是覆盖单个字段。5.3 让 Agent 输出对用户可读的结果解析完状态码后Agent 的最终输出应该回到业务语言。患者 Michael Jackson 的保险状态为有效。 自付额剩余2500 共付额150 原始 271 报文已保存到审计日志。这一步不能省略。用户不需要读 EDI但运营人员和系统审计一定需要保存原始 271以便出现争议时查证。6. 运行验证从启动网关到最终结果6.1 启动步骤先启动模拟 EDI 网关python mock_edi_server.py再启动 Agent 服务python agent_main.py然后用 curl 或 HTTP 客户端发送一条自然语言请求curl -X POST http://127.0.0.1:8000/agent/eligibility \ -H Content-Type: application/json \ -d {text: 查一下 Michael Jackson 的 Medicaid 是否有效会员号 JACKSONM服务提供者是 John DoeNPI 是 1234567891。}6.2 预期结果与自检点正常情况下响应 JSON 包含{ eligibility_status: ACTIVE, message: DIS$150 COPAY AFTER DED, deducible: 2500, copay: , original_271: ISA*00*... }如果出现eligibility_status: UNKNOWN优先检查模拟网关是否返回了 271 文本。271 中 HL*3 后是否跟着 EB 段。解析器是否把REF*6R*2500之后的内容识别为 REF 段。注意只验证“接口返回 200”是不够的。要分别验证三个层面HTTP 请求成功、270 报文通过语法检查、271 解析结果与期望一致。三层全通过才算执行层可用。7. 常见报错和排查链路7.1 报错现象、原因和处理方案报错现象常见原因检查位置处理建议270 报文被网关拒绝ISA 段发送方/接收方 ID 不足 15 位ISA 第 6、8 个元素用ljust(15)补齐空格270 报文被网关拒绝控制段 GS/ST/IEA 控制号不一致GS6、ST2、IEA2发送前检查三个控制号是否匹配271 解析不到 EB 状态HL 层级判断错误271 中的 HL 段与 NM1 段确认 HL*3 是否表示患者层(22)Agent 返回空状态模拟网关没收到 POST 或返回非 271 文本模拟网关日志、响应头打印原始响应文本确认格式LLM 提取字段缺失用户输入缺少 NPI 或会员号LLM 返回的 JSON在提示词里增加必填字段约束或增加校验日期格式错误使用 YYYY-MM-DD 而不是 X12 的 CCYYMMDDISA/GS/DTP 段统一使用datetime.strftime(%Y%m%d)循环嵌套错误HL 父层编号写错HL 的第 2 个元素按照 HL1 父为空、HL2 父为 1、HL3 父为 2 检查7.2 排查顺序先结构后业务X12 报错排查和普通 HTTP 调试不同要按从外到内的顺序查交换层ISA/IEA 是否合法发送方和接收方 ID 是否在对方系统有登记。功能组层GS/GE 是否合法功能组代码是否为 HS医疗资格。交易集层ST/SE 是否存在交易集控制号是否唯一。段顺序是否按 X12 标准定义的段顺序排列。循环嵌套HL 父层关系是否正确每个循环的起点终点是否明确。元素级别必填元素是否缺失枚举值是否合法长度是否超限。实际排错时建议先打印原始 EDI 文本用行号标注段序列再对照 X12 交易集手册逐段检查。不要只看错误码因为很多网关只会返回“TRANSACTION REJECTED”把具体原因藏在配套的 TA1 或 999 回执里。生产对接时必须解析 TA1 和 999 回执才能定位到具体段。8. 把最小 Agent 扩展成生产级医疗执行层8.1 本地示例和生产环境的差距本地模拟网关把 270 发到 HTTP 接口就能收到 271但真实医疗网络远不止如此。生产环境要面对保险公司或清算所提供的接入地址通常是 SFTP、HTTPS API 或 VAN且要求 TLS 证书。必须实现 TA1 确认、997/999 功能性确认才能知道报文是否被接收方语法接受。同一笔交易可能产生多条响应271 可能因分页或多次返回而拆分。发送方和接收方 ID、ISA 限定符、GS 版本号需要在对接测试环境中预先注册。生产报文需要保存完整原文、哈希或数字签名满足审计要求。这些差异决定了“本地跑通”和“生产上线”之间还有大量工程工作。8.2 X12 校验器是执行层最后一道闸门在 Agent 输出 270 后、真正发送之前必须插入一个独立的校验器。校验器应该检查必填段是否存在。枚举值是否合法例如服务类型代码 30 表示健康计划覆盖不能写成 33。日期格式是否严格为D8序列对应的CCYYMMDD。每个 HL 循环是否满足父子关系。ISA 定长字段是否满足长度要求。控制号是否在当前交换批次内唯一。建议把校验器做成 pytest 可调用的纯函数给每类交易集写 fixture这样 Agent 版本升级或模型替换后校验逻辑依然稳定。8.3 多交易集扩展方向跑通 270/271 之后同一个 Agent 平台可以扩展交易集扩展点新增能力837服务行、诊断码、CLM 段Agent 拆解病历生成理赔服务行835支付金额和调整原因自动对账识别拒付原因278授权请求和响应用 Agent 提前校验授权规则834批次注册批量处理成员变更扩展时不要为每个交易集重复造轮子。把 ISA/GS/ST 控制层、段遍历器、元素校验器做成公共模块每个交易集只实现自己的业务映射规则。8.4 审计与可观测性医疗 Agent 如果要进入正式业务必须能回答三个问题这个结果是谁生成的、依据哪条原始报文、实际发给了谁。因此日志至少要记录用户原始输入。LLM 提取出的结构化 JSON。Agent 生成的原始 270 文本。网关返回的原始 271、999 或 TA1。解析后的业务结果。本次交易的控制号和发送时间。这些日志不能只存在业务表里建议同时写一份独立的审计文件保留 EDI 原文方便后续交给合规团队检查。9. 最佳实践清单9.1 开发阶段清单先把 X12 生成器和解析器写成纯函数不依赖 LLM确保输入输出可测试。用固定 fixture 测试 ISA 层、GS 层、ST 层不要只测业务段。对每次生成都保留控制段快照避免控制号重复。用模拟网关先跑通 270/271再接入真实测试环境。9.2 上线前清单确认发送方 ID、接收方 ID 已经在目标环境注册。确认交易集版本例如 005010X279A1与接收方网关一致。接入 TA1 和 999 回执解析处理语法拒绝和业务拒绝。对 LLM 提取结果增加字段级校验必填、长度、枚举值。配置 X12 原文日志和审计留存周期。9.3 思考方式清单不要认为“LLM 能生成合法 JSON”就等于“能生成合法 X12”。不要用正则或字符串拼接硬扛复杂交易集。不要跳过回执解析否则你永远不知道报文为什么被拒。不要让下游系统直接消费自然语言结果先转成结构化业务对象。10. 下一步怎么深化医疗 AI Agent 的竞争力不在提示词技巧而在执行层能不能稳定、合规、可审计地连接医疗数据交换网络。X12 标准在这里扮演的是约束也是基础设施。一个 Agent 能生成几百字漂亮的理赔解释比不上一个能发出合法 837、解析 835 回执、自动识别拒付原因的 Agent 更有实际价值。读完这篇文章建议先不要急着接入真实保险公司。把最小 270/271 Agent 跑起来改几组字段看看模拟网关返回什么再写一个简单的校验器来拦截错误报文。这个过程会帮你建立对 X12 段结构、循环嵌套和控制号的直觉。下一步再考虑扩展 837 理赔、835 对账或者引入多 Agent 协同一个 Agent 负责解析用户输入一个 Agent 负责生成交易集一个 Agent 负责解析回执并总结异常。这种架构下每个 Agent 的职责边界会更清晰而 X12 标准就是所有 Agent 共同遵守的通信协议。