Agently 文档

中文

EN

中文

EN

Appearance

插件类型与接口细节 ​

本页基于 agently/types/plugins 的协议定义，强调“职责边界 + 典型场景 + 实现要点”。

1) PromptGenerator ​

职责：把结构化 Prompt 转为文本或消息列表，并生成输出校验模型。

关键方法：

  • to_text()：文本模型的最终 prompt
  • to_messages()：聊天模型消息列表
  • to_output_model()：生成 Pydantic 输出模型

典型场景：

  • 需要“自定义提示词格式”（例如内部 DSL）
  • 需要在消息中注入业务标签或元数据

最小实现要点：

  • 优先复用 DataFormatter 做结构化转换
  • 确保 to_output_model() 能与 ResponseParser 的解析策略匹配
python
from agently.types.plugins import PromptGenerator

class MyPromptGenerator(PromptGenerator):
    name = "MyPromptGenerator"
    DEFAULT_SETTINGS = {"$global": {"prompt.add_current_time": False}}

    def __init__(self, prompt, settings):
        self.prompt = prompt
        self.settings = settings

    def to_text(self):
        obj = self.prompt.to_prompt_object()
        return f"[SYSTEM]\n{obj.system}\n[INPUT]\n{obj.input}\n"

    def to_messages(self, *args, **kwargs):
        obj = self.prompt.to_prompt_object()
        return [
            {"role": "system", "content": str(obj.system or "")},
            {"role": "user", "content": str(obj.input or "")},
        ]

    def to_output_model(self):
        return self.prompt.to_output_model()

    def to_serializable_prompt_data(self):
        return self.prompt.get()

    def to_json_prompt(self):
        return self.prompt.to_json_prompt()

    def to_yaml_prompt(self):
        return self.prompt.to_yaml_prompt()

2) ModelRequester ​

职责：把 Prompt 转换为请求参数、发送请求、并统一输出流。

关键方法：

  • generate_request_data()：把 prompt + settings 变成模型 API 参数
  • request_model()：发送请求，返回异步流（raw SSE / chunk）
  • broadcast_response()：把 raw 流标准化为 Agently 事件流

推荐事件（ResponseParser 默认会用到）：

  • delta：流式文本增量
  • done：最终文本
  • original_delta / original_done：保留原始结构
  • reasoning_delta / reasoning_done：可选推理信息
  • tool_calls / meta / error：可选拓展

典型场景：

  • 接入私有推理服务、网关、多云路由
  • 输出需要拆成 delta + done 统一格式

实现要点：

  • broadcast_response() 是“系统标准化关键点”
  • 任何新事件都应在 ResponseParser 里明确处理逻辑

3) ResponseParser ​

职责：消费事件流，得到 text_result / parsed_result / result_object。

关键方法：

  • async_get_text()：拼接最终文本
  • async_get_data()：结构化输出解析
  • get_async_generator()：暴露流式事件

典型场景：

  • 需要解析“非标准 JSON”或流式结构化数据
  • 要把工具返回拼回最终结果

实现要点：

  • 推荐维护 full_result_data，包含：
    • text_result / parsed_result / original_delta / original_done
  • 对 JSON 解析建议统一入口，避免在多个地方做清洗

4) ToolManager ​

职责：管理工具注册、标签、调用、以及 MCP 接入。

关键方法：

  • register()：注册工具元信息与函数
  • get_tool_list() / get_tool_info()：检索
  • call_tool() / async_call_tool()：执行
  • use_mcp()：接入 MCP 工具源

典型场景：

  • 需要对工具调用做权限、沙盒或审计
  • 多租户工具隔离 / 动态加载工具

5) Session ​

职责：维护 full/current/memo 三类会话数据，并提供 resize 策略。

关键方法：

  • configure() / use_lite() / use_memo()
  • append_message()
  • async_resize() / async_judge_resize()
  • to_json() / load_json()

典型场景：

  • 需要自定义记忆策略（memo_update_handler）
  • 需要接入外部存储或“服务端会话”

实现要点：

  • memo 更新是可插拔的
  • resize 决定“裁剪 + memo 更新”是否发生

小结：何时写哪个插件 ​

  • PromptGenerator：你想改变 prompt 组织结构
  • ModelRequester：你要接入新模型 / 新协议
  • ResponseParser：你要解析新的输出结构
  • ToolManager：你要接管工具生态
  • Session：你要改变对话记忆策略