返回结构化 Rust 值

定义输出类型

用 Rust 类型表达模型与业务代码之间的契约。类型同时派生 Deserialize 和 JsonSchema；字段尽量具体，并为容易混淆的选项写清说明。

cargo add serde --features derive
cargo add schemars

use runifold::JsonSchema;
use serde::Deserialize;
 
#[derive(Debug, Deserialize, JsonSchema)]
struct Triage {
    category: String,
    urgent: bool,
    explanation: String,
}

不要在反序列化过程中执行写操作。解码完成后，再单独验证业务规则。

构建结构化 Agent

build_structured::<T>() 会把 Schema 加入请求，并返回强类型 Agent。运行结果既保留解析后的值，也保留完整的规范化执行结果。

let agent = runtime
    .agent("triage")
    .system("Classify the request. Keep the explanation short.")
    .build_structured::<Triage>("triage_result")?;
 
let result = agent.run("Payment failed twice", &run).await?;
println!("{:?}", result.output);
println!("turns: {}", result.outcome.turns);

生产环境应传入显式 RunContext，让预算、权限、取消和可观测性覆盖同一次调用。

验证与错误

需要区分两类失败：

服务商拒绝或忽略了输出格式；
返回的 JSON 无法反序列化，或不满足业务规则。

两者都应视为数据质量错误，不能静默退回未经验证的文本。可以记录响应 ID 与模型身份，但默认不要记录敏感正文。

服务商支持

结构化输出是一项能力契约：有的模型支持严格 Schema，有的只有 JSON 模式，兼容端点也可能声明了实际并未严格实现的能力。请测试线上使用的准确组合。

必须严格保证时，让能力策略失败关闭；允许降级时，应在产品行为与监控中明确暴露。