跳转到主要内容

​
@llm_chat

@llm_chat 创建一个多轮对话智能体。它管理历史记录、执行带工具的 ReAct 循环、支持流式响应，并可选地集成 SelfRef 实现持久化上下文。

​
基本用法

from SimpleLLMFunc import OpenAICompatible, llm_chat

models = OpenAICompatible.load_from_json_file("provider.json")
llm = models["openrouter"]["openai/gpt-4o"]


@llm_chat(llm_interface=llm, stream=True)
async def assistant(message: str, history: list | None = None):
    """
    You are a helpful, concise assistant.
    Answer directly without unnecessary preamble.
    """
    pass

​
历史记录管理

history 参数（或 chat_history）是特殊参数。框架会：
  1. 将你提供的 history 作为对话记录
  2. 追加当前用户消息
  3. 运行 ReAct 循环
  4. 在 output.messages 中返回更新后的历史记录
history = []

async for output in assistant("What is Python?", history):
    if is_response_yield(output):
        print(output.response)
        history = output.messages  # 保存以供下一轮使用

# 下一轮对话——智能体记得之前的对话
async for output in assistant("What are its main features?", history):
    ...
历史记录是外部管理的——你自行控制存储、持久化和分支。

​
流式传输

设置 stream=True 后，你会以事件的形式接收数据块： 
from SimpleLLMFunc.hooks import is_event_yield, LLMChunkArriveEvent

async for output in assistant("Tell me about Python", history):
    if is_event_yield(output):
        if isinstance(output.event, LLMChunkArriveEvent):
            print(output.event.accumulated_content, end="", flush=True)
    elif is_response_yield(output):
        history = output.messages
设置 stream=False 时，模型响应会作为单个 ResponseYield 一次性返回。

​
多模态用户消息

对于多模态 chat 输入，只使用一个 canonical user-message 对象：UserChatMessage。这样 @llm_chat 仍然是“一个用户回合”的 Agent 抽象，不会出现多套图片参数风格。 
from SimpleLLMFunc import llm_chat
from SimpleLLMFunc.type import ImgPath, ImgUrl, UserChatMessage

@llm_chat(llm_interface=llm, stream=True)
async def vision_agent(message: UserChatMessage, history: list | None = None):
    """Answer questions about user-provided images."""
    pass

async for output in vision_agent(
    UserChatMessage.multimodal(
        "Compare these images and list visible differences.",
        ImgUrl("https://example.com/reference.jpg", detail="high"),
        ImgPath("./candidate.png", detail="high"),
    ),
    history=[],
):
    ...
UserChatMessage.multimodal(...) 接受文本以及任意数量的 ImgUrl / ImgPath。它会归一化为 OpenAI-compatible user message，包含 text 与 image_url content parts。未来新增输入模态时也应扩展 UserChatMessage，而不是新增另一套 chat 输入约定。

​
工具

@llm_chat(llm_interface=llm, toolkit=[search, calculate], stream=True, max_tool_calls=10)
async def agent(message: str, history: list | None = None):
    """
    A research assistant. Use search for facts, calculate for math.
    Always cite your sources.
    """
    pass
ReAct 循环自动处理工具调用：
  1. LLM 决定调用工具 → ToolCallStartEvent
  2. 框架执行工具 → ToolCallEndEvent
  3. 运行时将工具结果记录为内部对话记录补丁
  4. 重新编译上下文 → LLM 看到修补后的对话记录 → 决定下一步操作
max_tool_calls 限制每次调用中工具调用的总次数。默认值由框架定义。None 表示不限制。

​
SelfRef 集成

对于需要持久化记忆、上下文压缩或子智能体分叉的场景： 
from SimpleLLMFunc.builtin import PyRepl

repl = PyRepl()


@llm_chat(
    llm_interface=llm,
    toolkit=[*repl.toolset],
    stream=True,
    self_reference_key="agent_main",
)
async def coding_agent(message: str, history: list | None = None):
    """
    A coding agent with persistent memory.
    Use runtime.selfref.context.remember(...) to store durable lessons.
    Use runtime.selfref.context.compact(...) when context grows large.
    """
    pass
设置 self_reference_key 后，框架会：
  • 将 SelfReference 后端绑定到该 key
  • 为每次调用创建 SelfRefSession
  • 在 PyRepl 中提供 selfref 原语
  • 每轮对话后持久化更新的历史记录
详见 SelfRef 了解完整的上下文模型。

​
模板参数

在运行时向系统提示词注入动态值： 
@llm_chat(llm_interface=llm, toolkit=[...])
async def agent(message: str, history: list | None = None):
    """
    You are an assistant for {project_name}.

    Workspace: {workspace_path}
    Git branch: {git_branch}
    """
    pass

async for output in agent(
    "Fix the bug",
    history,
    _template_params={
        "project_name": "MyApp",
        "workspace_path": "/src",
        "git_branch": "main",
    },
):
    ...

​
返回模式

模式行为
"text"（默认）output.response 是最终的文本字符串
"raw"output.response 是提供商返回的原始消息字典

​
系统提示词构建

对于 @llm_chat，最终的系统提示词由多个来源构建：
  1. 文档字符串 → 基础系统提示词（应用模板参数后）
  2. 工具最佳实践 → 以 <tool_best_practices> 块添加到前部
  3. 必要原则 → 以 <must_principles> 块追加到末尾（使用原生工具调用）
  4. SelfRef 经验 → 如果激活则渲染到系统提示词中
  5. 历史记录中最新的系统消息 → 如果存在则覆盖文档字符串
将文档字符串编写为稳定的智能体策略——身份定义、行为规则和长期约束。将每轮变化的上下文放在参数或模板参数中。

​
并发会话

可以同时运行多个独立的对话： 
# 每次调用使用独立的历史记录——没有共享状态
task1 = assistant("Question A", history_a)
task2 = assistant("Question B", history_b)

# 并发执行
results = await asyncio.gather(
    consume_stream(task1),
    consume_stream(task2),
)

​
参数参考

参数类型默认值说明
llm_interfaceLLM_Interface必填要调用的模型
toolkitList[Tool]None可用工具
max_tool_callsint | None框架默认值工具调用次数限制
streamboolFalse启用流式传输
self_referenceSelfReference | NoneNone显式指定 selfref 后端
self_reference_keystr | NoneNone自动为该 key 创建 selfref
**llm_kwargsAny—传递给 LLM 的参数（temperature 等）
调用时的特殊参数：
  • _template_params: Dict[str, Any] — 模板值
  • _abort_signal: AbortSignal — 取消信号
  • _too_long_to_file: bool — 将过长的工具结果截断并写入文件
→ API 参考：装饰器