Solon v3.9.0

agent - 两种调用范式

</> markdown
2026年1月24日 下午11:15:51

在 Solon AI 中，智能体的调用被设计为两个层级：面向开发者体验的流式增强接口 以及 面向底层扩展的原始能力接口。这种设计既保证了日常开发的便捷性，又满足了复杂流式编排的定制需求。

1、增强型流式接口：prompt（体验简单，使用方便）

prompt 接口返回一个 AgentRequest 对象。它采用了 Fluent API 设计模式，允许你以声明式的方式配置单次请求的参数（如临时拦截器、模型参数覆盖、会话注入等）。不同的智能体实现（如 SimpleAgent, ReActAgent, TeamAgent）通过该接口提供差异化的增强能力。

使用示例：

ReActAgent agent = ReActAgent.of(chatModel)
                .modelOptions(o -> o.temperature(0.1F)) // 低温度保证推理逻辑的一致性
                .defaultToolAdd(new WeatherTools())
                .build();


ReActResponse resp = agent.prompt("你好")
                          .session(mySession) //可选
                          .options(o -> o.maxSteps(5)) //可选
                          .call();

结果载体：AgentResponse

与简单的消息返回不同，prompt().call() 返回的是一个包含完整执行上下文的 AgentResponse 实现类。以 ReActResponse 为例，它不仅包含结果，还提供了推理轨迹和指标：

方法说明核心价值
getTrace()获取执行轨迹 (Trace)逻辑审计： Agent 的思考链条与工具调用记录，用于调试与合规审计。（可选项，有些智能体会没有）
getContext()获取底层的 FlowContext底层穿透：直接访问工作流级别的上下文变量与环境数据，实现与宿主系统的深度交互。
getMetrics()获取度量数据 (Metrics)性能监控：精确监控单次任务的 Token 消耗、工具调用频次及执行总耗时，支撑成本分析。
getMessage()获取原始助手消息 (Message)原子访问：获取包含元数据（如角色、函数调用参数等）的原始 AssistantMessage 对象。
getContent()获取纯文本回答 (Content)快速集成：直接提取 AI 最终生成的文本结论，适用于对话展示或简单的文本分析。
toBean(Class<T>)结构化反序列化 (Bean)语义对齐：将 AI 生成的 JSON 文本自动映射为 Java 强类型实体，实现“从非结构化到结构化”的闭环。

2、原始接口：call, run（主要是，内部或测试时使用）

Agent 的核心接口定义了智能体作为“计算单元”的最简形态。虽然直接使用不如 prompt 方便，但它是接入 Solon Flow 分布式工作流的唯一标准。

public interface Agent extends AgentHandler, NamedTaskComponent {
    //指定指令的任务执行（开始新任务）
    AssistantMessage call(@Nullable Prompt prompt, AgentSession session) throws Throwable;

    //Solon Flow 节点运行实现
    @Override
    void run(FlowContext context, Node node) throws Throwable ;
}

使用示例：

ReActAgent agent = ReActAgent.of(chatModel)
                .modelOptions(o -> o.temperature(0.1F)) // 低温度保证推理逻辑的一致性
                .defaultToolAdd(new WeatherTools())
                .build();


AssistantMessage message = agent.call(Prompt.of("你好"), InMemoryAgentSession.of("session_001"));

3、总结与选择建议

比较维度增强接口 (prompt)原始接口 (call/run)
易用性⭐⭐⭐⭐⭐ (流式 API，语义清晰)⭐⭐⭐ (需要手动处理较多参数)
信息量丰富 (包含 Trace, Metrics, Session)简约 (仅返回 AssistantMessage)
应用场景业务代码、交互式应用、复杂 Agent 协作框架扩展、自定义 Node 实现、工作流引擎驱动
契约关系面向具体的实现类（如 ReActAgent）面向抽象的接口定义 (Agent)