Agent 与 Context#

agent() 执行模型工具循环。Agent 保存可复用配置，并为普通子类方法建立作用域。Context 提供命名内容与历史选择。所有入口复用现有 Runtime 和 Session DAG。

直接调用与 Agent 类#

普通调用不需要手动构建或绑定 Context。

from openprogram import Agent, agent, agent_async

answer = agent("Summarize this text", tools=[])

class Researcher(Agent):
    instructions = "Return a short, factual answer."
    tools = []

    def prepare(self, question):
        """Remove surrounding whitespace."""
        return question.strip()

    def research(self, question):
        """Answer the prepared question."""
        return self(self.prepare(question))

researcher = Researcher(model="configured-model")
answer = researcher.research("A question")
# 异步代码：answer = await researcher.arun("A question")
# 或：answer = await agent_async("A question", tools=[])

agent() 接收字符串或内容块，可指定 model、effort、tools、choices 和 runtime。choices 让收尾回复成为一次下一步决策，并返回解析后的选择结果。工具执行选项见 Runtime。tools=None 选择可用工具，tools=[] 禁用工具。agent_async() 使用同样的选项。

Agent(model=..., instructions=..., context=..., tools=..., runtime=..., effort=..., **options) 用实例设置覆盖类默认值，调用参数再覆盖实例设置。Agent.from_spec(spec, **overrides) 使用现有 AgentSpec 配置，不创建已保存 Agent 条目。

构造对象不请求模型，也不创建执行会话。调用继承当前执行；没有外层执行时创建独立执行，并在结束时释放资源。复用实例不自动续接上一次独立会话。

普通实例方法、静态方法与类方法自动建立调用作用域，包括单下划线帮助方法。双下划线特殊方法与生成器不采集。方法记录不会注册模型工具。在对应 method_options 设置 "tool": True 可显式登记工具。 method_options = {"method_name": {"expose": "io", "render_range": {...}}} 无需装饰器即可设置方法元数据。

Context 内容与可见性#

框架自动派生并绑定 Context。显式配置是可选的：

from openprogram import Agent, Context

context = Context(
    {"notes": "Use the project terminology."},
    providers={"current_topic": lambda current: "Agent context"},
)
researcher = Agent(context=context, tools=[])

Context(blocks=None, *, parent=None, providers=None, history_filter=..., call_id=..., store=None, head_id=None) 是命名内容的可变映射。derive() 创建具有独立内容的子上下文。Context.current() 返回当前任务绑定，无绑定时返回 None。merge(other) 覆盖命名内容和显式选择规则，不替换作用域调用身份。宿主集成可使用 bind() 显式绑定。

提供函数是接收当前 Context 的同步 Python callable，在每次模型请求时运行。提供函数失败会终止该请求。框架不执行表达式字符串。

history_filter 默认为 "dag"。"current_call" 从已可见的 DAG 节点中选择当前作用域与其后代调用，False 禁用历史。callable 接收 (node, context)，在已有 DAG 可见性检查之后过滤节点。这些设置不能扩大工具权限。

Context 使用同一模型：父继承、命名内容、请求时求值和历史可见性。Agent 实例内容是该模型的实例绑定。模型交互仍归执行会话保存。内容与系统指令、工具权限分别处理。

显式会话生命周期#

多次独立调用需要续接同一会话时，使用 Context(store=writer, head_id=None)。writer 是现有 SessionNodeWriter：

from openprogram import Agent, Context
from openprogram.store import SessionStore, SessionNodeWriter

store = SessionStore(root_path="/var/lib/myapp/sessions")
store.create_session("research", agent_id="main")
writer = SessionNodeWriter(store, "research")
researcher = Agent(context=Context(store=writer), tools=[])
try:
    first = researcher("List the project requirements.")
    second = researcher("Review the requirements from the previous call.")
finally:
    store.close()

head_id 选择已有分支末端作为初始前序节点。None 续接当前会话末端。调用者拥有并关闭显式 store，执行作用域不会关闭它。

该显式 Context 会话提供 NOOA 式重复实例调用需要的事件生命周期，复用已有 Session DAG。Agent 仍保存配置，默认调用保持独立。

受管 Program 源码#

受管加载器采集显式授权包目录内的源码函数，包括已选择的第一方源码、已安装及目录登记的 Program 包、所有者登记的外部 harness、已发布 Program 与保留源码快照。采集包含子模块与嵌套源码定义。任意宿主文件、无关依赖、lambda、动态生成代码与不可用源码不在该范围内。

包通过 PROGRAM_ENTRIES 列出公开入口。普通入口可用显式 __agent_options__ 映射提供已有入口元数据。被采集的帮助函数不会自动成为工具。加载器保留方法配置，并排除生成器采集。

内置 text workflow 使用普通 TextAgent 方法。summarize_text 调用 agent(..., tools=[])。模块导出保留公开名称与表单元数据。

类与方法接口参考 NVIDIA-labs OO Agents。OpenProgram 不声称 NOOA API 兼容。

方法配置#

普通 Agent 方法产生 code 节点，模型请求产生 llm 节点。Agent 承担方法元数据、执行控制与显式登记。Context 动态构建每次请求。

Agent 定义方法执行、配置与登记，Context 动态构建每次请求。

用法#

from openprogram import Agent
from openprogram.agentic_programming import llm

class ExampleAgent(Agent):
    method_options = {
        'f': {'tool': True},
    }

    def f(self, x: str) -> str:
        """One-line summary of what f does."""
        return llm([{"type": "text", "text": f"...{x}..."}])

_example_agent = ExampleAgent()
f = _example_agent.f

每个普通方法自动建立调用作用域。通过类的 method_options 映射配置指定方法。

方法配置#

执行与 Context 设置#

工具注册参数#

设置 tool=True 的 Agent 方法注册进共享注册表(openprogram.programs),成为 LLM 可调用的工具,与 @function 装饰的工具并列。以下参数控制这次注册,名字和语义与 @function 一致:

函数名、参数名 / 类型 / 默认值、一句话摘要都从函数签名和 docstring 自动读取,不在 method_options 中重复。

选择 Runtime#

方法在它所属 Agent 配置的 Runtime 上运行;Agent 没有配置时用调用方的:ExampleAgent(runtime=rt).f("x") 让 f 及其中每次模型请求都在 rt 上运行,它调用的 Agent 方法也继承 rt。Runtime 在程序入口(CLI、脚本、测试)配置,不通过方法参数往下传。一个工作流要用两个模型时——比如作者和评审——给第二个角色一个自带 Runtime 的 Agent 实例。

Runtime 注入#

旧函数仍可能声明名为 runtime、exec_runtime 或 review_runtime 的参数,它们会自动注入:调用方没传(或传 None)时,先从当前调用链取 runtime;作为入口调用时经 create_runtime()(自动检测)新建,函数返回时再关闭。一个函数可以声明多个 runtime 参数,全部填同一个 runtime。这些参数不会出现在 LLM 工具 schema 和 WebUI 表单里。新写的方法不声明这些参数。

自省与安全#

• fn.spec — 自动生成的 JSON-schema 工具 spec({"name", "description", "parameters"});fn.execute(**kwargs) 用 LLM 提供的 kwargs 调用 wrapper。
• 自递归兜底:函数自我重入超过 5 层抛 RecursionError(注入的情境 prompt 也会引导模型不要自调用)。
• 预调用钩子(add_pre_invocation_hook / remove_pre_invocation_hook)在每次调用开头运行,可以抛 CancelledError 中止本次调用(WebUI 的停止按钮就是这么实现的)。

记录到 DAG#

• 进入函数:写一个 code 节点(output=None, status="running"),函数 docstring 一并存进该节点的 metadata.doc,渲染上下文时拼在 函数名(参数) 前面。
• 函数体内 llm():每次调用写一个 llm 节点。
• 退出函数:回填同一个 code 节点的 output / status。

expose="hidden" 时不写任何节点。standalone 运行(没安装 DAG store)时记录全部 no-op,函数照常执行。

可恢复步骤与代码版本#

为同步编排函数声明 method_options = {"report": {"resumable": True}}，将外部操作放入 step("稳定名称", 操作函数, *args, **kwargs)。步骤输入和结果必须可保存为 JSON；继续执行时，已完成步骤直接返回保存的结果，不再调用操作函数。重复名称按出现次数区分，已执行步骤的顺序和输入必须保持兼容。

嵌套编排使用 workflow("名称", 函数, *args, **kwargs)。并行编排使用 parallel({"分支名": (函数, args, kwargs)})；各分支独立保存进度，所有分支停止后才释放任务所有权。

设置项 execution.code_change_policy 默认是 keep_original，继续使用保存的原函数和 Python 辅助函数源码；use_latest 保留已完成步骤的结果，并用当前代码执行后续兼容步骤。任务的“继续”操作可以覆盖此设置。A 已采用 B 后，再更新到 C 时选择保留原代码，会继续 B；尚未通过已有进度兼容性检查的候选版本不会取代已采用版本。新代码需要转换局部状态时，应在剩余步骤之前通过纯编排代码转换已保存的 JSON。已记录步骤被删除、重排、输入不兼容或固定依赖不可用时，任务保持暂停。权限和工具参数约定仍然需要通过兼容性检查。

手动调用恢复原执行记录；聊天调用将最终结果交给原来的待完成工具调用。重启导致的中断沿用两小时自动继续期限。主动暂停、取消、未回答的授权请求以及结果不确定的外部操作不会自动重试。

此功能在显式步骤处恢复，不保存任意 Python 调用栈。步骤外的外部调用和状态修改、异步编排、生成器、活动句柄及非 JSON 结果不支持此恢复约定。外部操作已经开始、但结果尚未保存时进程退出，必须先核对操作结果。函数运行界面显示是否声明可恢复步骤，普通函数中断后需要重新运行。

步骤之间不得依赖可变的 Python 全局变量、闭包或默认参数。需要持续保存的状态应通过步骤的 JSON 输入和结果传递，进程内变量修改不能作为恢复依据。

步骤依赖需要在模块级导入；辅助函数内部导入、动态导入 API 和动态生成代码会在执行步骤前被拒绝。Python 辅助函数源码递归保存。模块和类对象目前仅支持固定的标准库身份，第三方及用户包对象会被拒绝，因为只保存包初始化文件无法确定完整实现。

会话轮次与恢复#

Agent.run_turn(request, *, context=None, on_event=None, cancel_event=None, execution_context=None) 返回 TurnResult。从 openprogram 导入 TurnRequest 和 TurnResult。新轮次执行前应用实例配置；Context.for_session(store, session_id, head_id=..., blocks=..., providers=...) 绑定持久化存储和分支。请求与 Context 的会话不一致时拒绝执行。Context.session_id 返回所选图的标识。

arun_turn(request, **options) 提供协作式取消的异步执行。resume_turn(continuation, **options) 与 aresume_turn(...) 复用断点请求，不重复执行准入。事件回调在执行线程接收现有运行时事件字典。持久化暂停和执行中追加输入沿用已有执行控制及安全点协议。

ChatAgent 继承这套契约，是实际聊天使用的类型。子类重写轮次入口时，不会将其自动包装为普通函数调用。旧 openprogram.agent.dispatcher 导入与共享 openprogram.agent.turn_runtime 指向同一模块，不再维护另一份执行循环。