运行时原语
Primitives 是可以在execute_code（PyRepl）内部通过 runtime.<namespace>.<name>(...) 调用的函数。它们让工具能够在不打破工具边界的情况下访问 Agent 级别的能力。
概念
| 概念 | 含义 |
|---|---|
| PrimitivePack | 一组相关原语及其后端的命名集合 |
| RuntimePrimitiveBackend | PrimitivePack 所包装的有状态对象（例如 SelfReference） |
| @primitive | 将函数注册为可调用原语的装饰器 |
| PrimitiveSpec | 暴露给模型的契约（名称、描述、参数、最佳实践） |
| PrimitiveCallContext | 传递给原语处理函数的运行时上下文 |
内置原语：SelfRef Pack
框架内置了一个 Pack ——selfref —— 提供 6 个原语：
runtime.selfref.context.inspect()
runtime.selfref.context.remember(text)
runtime.selfref.context.forget(experience_id)
runtime.selfref.context.compact(goal, instruction, ...)
runtime.selfref.fork.spawn(task, instruction, ...)
runtime.selfref.fork.gather_all(include_history=False)
创建自定义 Pack
1. 定义 Backend
from SimpleLLMFunc.runtime import RuntimePrimitiveBackend
class MetricsBackend(RuntimePrimitiveBackend):
def __init__(self):
self.counters: dict[str, int] = {}
def increment(self, name: str, amount: int = 1) -> int:
self.counters[name] = self.counters.get(name, 0) + amount
return self.counters[name]
def get_all(self) -> dict[str, int]:
return dict(self.counters)
2. 定义 Primitives
from SimpleLLMFunc.runtime import primitive, PrimitiveCallContext
@primitive
async def increment_counter(
ctx: PrimitiveCallContext,
name: str,
amount: int = 1,
) -> dict:
"""
Increment a named counter and return its new value.
Args:
name: Counter name.
amount: How much to add. Default 1.
Returns:
Dict with counter name and new value.
Best Practices:
- Use descriptive counter names (e.g., "files_processed", "errors_found").
- Use this to track progress across tool calls.
"""
backend: MetricsBackend = ctx.backend
new_value = backend.increment(name, amount)
return {"name": name, "value": new_value}
@primitive
async def get_metrics(ctx: PrimitiveCallContext) -> dict:
"""
Get all current counter values.
Returns:
Dict of all counter names to their current values.
Best Practices:
- Call this to report progress summaries.
- Useful before context compaction to record final metrics.
"""
backend: MetricsBackend = ctx.backend
return backend.get_all()
Primitive 的 docstring 必须包含
Best Practices 部分。缺少该部分将导致注册失败。3. 构建 Pack
from SimpleLLMFunc.runtime import PrimitivePack
metrics_pack = PrimitivePack(
namespace="metrics",
backend=MetricsBackend(),
primitives=[increment_counter, get_metrics],
guide={
"namespace": "metrics",
"overview": "Track numeric counters across tool calls.",
"best_practices": {
"when_to_use": "To track progress, count occurrences, or measure work done.",
"pattern": "Increment during work, get_metrics at milestones.",
},
},
)
4. 安装到 PyRepl
from SimpleLLMFunc.builtin import PyRepl
repl = PyRepl()
repl.install_primitive_pack(metrics_pack)
runtime.metrics.increment_counter("files_read")
runtime.metrics.get_metrics()
可发现性
模型通过内置的元原语来发现可用的 Primitives：runtime.list_primitives() # 所有可用的原语名称
runtime.get_primitive_spec("metrics.increment_counter") # 完整契约
runtime.list_backends() # 已安装的 backend packs
PrimitiveCallContext
每个原语处理函数都会接收一个上下文对象：@dataclass
class PrimitiveCallContext:
backend: RuntimePrimitiveBackend # Pack 的 backend 实例
fork_context: Optional[ForkContext] # Fork 信息（如果在 fork 内部）
event_emitter: ToolEventEmitter # 发送自定义事件
ctx.event_emitter 可以在长时间运行的原语中流式推送进度。
→ API 参考：Runtime