API 指南总览

本章按功能讲解 xun 包暴露的 API：示例中的导入名与签名与源码一致，标为「伪代码」的片段只示意行为。跑示例前先设好 XUN_OPENAI_BASE_URL 与 XUN_OPENAI_API_KEY（见配置）；更多可执行示例见仓库根目录的 demo.ipynb。

模块地图

flowchart LR
  ENTRY["入口<br/>entrypoint.py"] --> AGENT["智能体<br/>agent.py"]
  CONFIG["配置<br/>config.py"] --> AGENT
  AGENT --> LOOP["执行循环<br/>loop.py"]
  HOOKS["钩子与命令<br/>hooks.py · command.py"] --> LOOP
  LOOP --> CONV["会话与压缩<br/>conversation.py · compact.py"]
  LOOP --> TOOLBOX["工具<br/>toolbox.py · tools"]
  LOOP --> DISPLAY["显示<br/>display_abstract.py · displays"]
  EXT["扩展<br/>extension.py"] --> AGENT

公共导出

from xun import ... 可用的名字（见 src/xun/__init__.py）：

分组	名称
智能体	Agent、AgentConfig、Workspace
工具	ToolBox、ToolCallContext、tool_attr
子智能体	AgentGetterProtocol、AgentGetterParam
显示	DisplayAbstract、Display、NullDisplay、WebDisplay、WebDisplayService
命令与钩子	Command、CommandRegistry、HookArgs、Hooks
压缩	CompactorAbstract、AutoCompactor
会话入口	setup_agent、interactive_session、web_session、main、main_serve、main_container
结果类型	Result、ToolResultType、ErrorInfo、CancelledError
扩展	ExtensionContext、extension_attr、xun_version

生命周期状态命名空间 T（T.Uninit / T.Init / T.Final）不在 __all__ 中，通过 Agent.T 访问。

最小骨架

from xun import Agent, AgentConfig, ToolBox, NullDisplay

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

agent = Agent(
    toolbox=ToolBox().register(add),
    display=NullDisplay(),
    config=AgentConfig.default(),      # 跳过 config.json，但仍从 os.environ 取 ${XUN_*}
).initialize()

answer = agent.instruct("What is 2 + 3?").execute()
if answer.is_ok():
    print(answer.unwrap())
else:
    print(answer.unwrap_err().error)

需要一整套内置工具、默认系统提示与会话命令时，改用 setup_agent(default_tools=True)，它返回的已是初始化后的智能体。

术语

术语	含义
工具（tool）	注册进 ToolBox 的普通可调用对象，以 JSON Schema 形式暴露给模型
轮 / 步（step）	一次模型调用及其引发的工具调用集合
事件（event）	智能体向显示层广播的载荷（ToolCallEvent、InfoEvent …）
钩子（hook）	执行路径上的可注册回调，参数对象可就地修改
扩展（extension）	放在 $XUN_HOME/extensions/ 下、在每个智能体初始化时重放的源文件
工作区（workspace）	智能体可读写的目录集合：workdir + 惰性临时目录