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



### 1、增强接口：prompt (面向业务逻辑)

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


**使用示例：**


```java
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 分布式工作流的唯一标准。

```java
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 ;
}
```

使用示例：

```java
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)     |