让Agent输出界面:结构化JSON渲染实践
作者:新兰2026.11.17 03:34浏览量:0简介:本文介绍如何让AI Agent输出结构化JSON形式的界面描述,由前端解析渲染并回传用户事件。内容包括可选children的最小Schema、约束型Prompt、带校验、重试与深度限制的调用代码、组件白名单以及后端动作鉴权,适合需要接入多个模型并落地Agent界面的开发者参考。
传统Agent通常返回自然语言。前端要再次理解回复的意图,才能拼出按钮、表单或卡片。这个过程容易带来样式不统一、交互难控制、结果难复用的问题。
一种更直接的做法是让Agent输出界面描述。模型不负责画界面,只负责输出一份前端可以解析、渲染和响应的结构化JSON。只要模型能稳定生成这份JSON,它就可以和具体的模型服务解耦,OpenAI、Claude、Gemini等不同来源的模型都能作为推理后端。
本文讨论的是这类”声明式UI描述”的实现思路。文中不引用任何特定官方规范。实际接入前,请查阅所用协议的官方文档,确认版本与字段定义。
agent-">一、Agent为什么要输出界面描述
自然语言回复适合阅读,但不适合直接操作。假设用户问”我的订单到哪了”,纯文本回复只能给出一段话。如果回复是一个包含订单状态、查看详情按钮和申请退款按钮的卡片,用户就能直接完成下一步操作。
界面描述把页面拆成树形结构。每个节点有类型、属性、子节点和动作。前端按类型找到对应组件,按属性设置内容,按动作绑定事件。用户点击按钮或提交表单后,前端把事件对象回传给Agent,Agent再生成下一轮界面。
一个最小的输出示例如下:
{"type": "container","props": {"direction": "vertical"},"children": [{"type": "text", "props": {"content": "你的订单已生成"}},{"type": "button","props": {"label": "查看详情"},"actions": [{"type": "onClick", "target": "show_order"}]}]}
二、与function calling的区别
function calling的作用是让模型输出要调用的函数名和参数,由程序执行函数后再把结果交还模型。界面描述则是让模型输出页面本身。两者可以配合使用。例如,Agent先通过function calling查询订单数据,再把查询结果组织成界面描述输出。
三、模型解耦与选型指标
界面描述是协议层的约定,不依赖某一家模型。模型对它的核心要求是稳定输出符合约定的JSON,而不是擅长设计页面。选型时可以重点看四个指标:
- 结构化输出稳定性:能否稳定返回JSON,而不夹杂解释文字。
- 指令遵循能力:能否按字段、组件和动作约束生成内容。
- 成本与延迟:界面生成的链路较短,但高频调用仍要关注Token成本。
- 接入方式:是否支持统一API、流式输出、函数调用或JSON模式。
如果团队需要同时接入多个模型,通常会建设一层统一接入层,屏蔽不同提供商的接口差异。下文的代码都假设调用经过这样一层。
四、定义最小Schema
不要一开始就设计复杂组件。建议先支持五类节点:container、text、button、input、list。每个节点必须包含type和props。children和actions为可选字段,文本和按钮这类叶子节点可以不写children。
动作只允许白名单事件,例如onClick、onSubmit、onChange。这样可以避免模型生成任意脚本。
ALLOWED_TYPES = {"container", "text", "button", "input", "list"}ALLOWED_ACTIONS = {"onClick", "onSubmit", "onChange"}UI_SCHEMA = {"type": "object","required": ["type", "props"],"properties": {"type": {"type": "string", "enum": sorted(ALLOWED_TYPES)},"props": {"type": "object"},"children": {"type": "array", "items": {"$ref": "#"}},"actions": {"type": "array","items": {"type": "object","required": ["type", "target"],"properties": {"type": {"type": "string", "enum": sorted(ALLOWED_ACTIONS)},"target": {"type": "string"}}}}}}
其中"$ref": "#"表示children中的每个节点都要满足同一套规则,从而支持递归嵌套。
五、设计约束型Prompt
Prompt要明确三件事:只输出JSON,字段必须符合Schema,不得生成未定义的组件。示例如下:
你是UI生成Agent。请根据用户需求输出A2UI类JSON。只能使用container、text、button、input、list组件。每个节点必须包含type和props,children与actions可选。不要输出Markdown,不要解释,不要包含注释。
Prompt只能降低出错概率,不能保证输出正确。程序必须再做一次校验。
六、调用模型并校验结果
下面的代码修正了三个常见问题。第一,OpenAI风格的响应中,choices是数组,需要取第一个元素。第二,HTTP错误、空结果和非JSON内容都要单独处理。第三,重试次数、退避时间和嵌套深度都有上限。
```python
import json
import logging
import os
import time
import requests
from jsonschema import ValidationError, validate
API_URL = os.environ[“UNIFIED_API_URL”]
API_KEY = os.environ[“UNIFIED_API_KEY”]
UI_MODEL = os.environ.get(“UI_MODEL”, “your-model-name”)
MAX_RETRIES = 2 # 最多重试2次,共最多3次调用
MAX_DEPTH = 6 # 页面最大嵌套层级
TIMEOUT = 30 # 单次请求超时秒数
SYSTEM_PROMPT = “你是UI生成Agent,只输出A2UI类JSON。”
logger = logging.getLogger(“ui_agent”)
def max_depth(node, depth=1):
children = node.get(“children”, [])
if not children:
return depth
return max(max_depth(child, depth + 1) for child in children)
def call_model(user_input):
payload = {
“model”: UI_MODEL,
“messages”: [
{“role”: “system”, “content”: SYSTEM_PROMPT},
{“role”: “user”, “content”: user_input},
],
“response_format”: {“type”: “json_object”}, # 仅部分提供商支持,见第七节
}
headers = {“Authorization”: f”Bearer {API_KEY}”}
resp = requests.post(API_URL, json=payload, headers=headers, timeout=TIMEOUT)
resp.raise_for_status()
data = resp.json()
choices = data.get(“choices”) or []
if not choices:
raise ValueError(“模型返回的choices为空”)
return choices[0][“message”][“content”]
def fallback_ui():
return {“type”: “text”, “props”: {“content”: “页面暂时无法生成,请稍后重试。”}}
def generate_ui(user_input):
last_error = None
for attempt in range(MAX_RETRIES + 1):
try:
content = call_model(user_input)
ui = json.loads(content) # 非JSON时抛出ValueError
validate(instance=ui, schema=UI_SCHEMA)
if max_depth(ui) > MAX_DEPTH:
raise ValueError(“页面嵌套层级超过上限”)
return ui
except (requests.RequestException, ValueError, KeyError, ValidationError) as e:
last_error = e
logger.warning(“第%d次生成失败: %s”, attempt + 1, e)
if attempt < MAX_RETRIES:
time.sleep(min(2 ** attempt, 8)) # 指数退避,上限8秒
logger.error

登录后可评论,请前往 登录 或 注册