跳转到主要内容
Chinese, Simplified

category

正文

披露:我是 PRAXO-CORE 维护者。本文基于 2.10.0 公开范围;不是生产、安全或平台兼容性认证。

在 Lua 里实现 Agent 循环,和 Python 很不一样。

Lua 没有大型标准库,没有动态对象系统,也没有一个默认的“服务运行时”。它经常是宿主里的扩展语言:游戏引擎、网络设备、IoT 控制面、插件系统。

这些宿主不拥有整个运行时,却握着状态、配置、连接和业务钩子。加一个 Python sidecar 可能不可行。PRAXO-CORE 的 Lua SDK 是一个工程实验:不重写扩展,而是在宿主进程里放一个受治理的 Agent 循环。

这篇文章拆三件事:模块、表/函数设计、Lua 5.4 边界。

一、入口:run_agent

核心调用:

local agent = require("praxo.agent")
local models = require("praxo.models")

local model = agent.static_model("hello")
local options = agent.agent_options(model)
local result = agent.run_agent(options, models.session({ id = "demo" }), "hello")
print(result.output)

接口很小,但背后包含:options、model、session、tool registry、policy、event sink、checkpoint、context budget、middleware。

二、模块:用 Lua 的方式表达 Agent

Module Surface
agent Agent 循环、options、tool registry、function tool
models message、request、response、usage、session、event、decision、memory record、context budget、stream kinds
runtime event sink、path checker、memory store、checkpoint allowlist、context budget、token estimate
toolcall tool-call 解析、markup 移除
jsonschema schema 校验
plugin manifest 解析
middleware call limit、fallback、PII 脱敏、structured output、tool selection

Lua 没有 Python 的动态对象系统,所以记录用 table 表达,model/tool 用函数表达,tool registry 持有 function tool。这个设计很 Lua:不引入大型对象框架,直接用语言本身的组合能力。

三、工具:函数作为工具实现

注册工具:

local registry = agent.tool_registry()
agent.register_tool(registry, agent.func_tool("echo", "Echo arguments", function(arguments)
  return arguments
end))
options.tools = registry
options.max_steps = 8

关键不是“能注册函数”,而是工具调用的边界:

  • 工具参数要经过解析和校验;
  • 工具调用要经过策略;
  • 工具结果要能被事件和检查点记录;
  • 失败要传播,不能静默吞掉。

四、Lua 5.4 边界

这是最重要的工程约束:

  • 仅 Lua 5.4;
  • 不宣称 LuaJIT 兼容;
  • 不宣称 Lua 5.1 / 5.3 兼容;
  • 不宣称 OpenResty 兼容;
  • 不宣称 Redis 兼容。

很多流行的 Lua 宿主使用 LuaJIT 或更老的 Lua 版本。公开材料如果只写“Lua”,会误导读者。更诚实的说法是:这是 Lua 5.4 的原生 Core 循环;如果你的宿主是别的 Lua 运行时,需要单独做移植评估。

五、标准库 only

Lua 宿主动辄关心 footprint。这个 SDK 刻意做小:

  • 只依赖 Lua 标准库;
  • 没有 Python host;
  • 没有 provider SDK;
  • 核心循环不需要编译扩展。

这不等于“绝对零依赖”,但它把依赖面做小、做可审计。在嵌入式宿主里,这经常是“能不能评估”和“能不能部署”的区别。

六、三个 partial 面

必须明确:

  1. event sink:覆盖向量行为和常见路径,但不是每个可选 Go hook;
  2. stream part:有 stream kind 表示,但不是异步运行时;
  3. JSON Schema:覆盖向量定义行为,但不是完整 JSON Schema。

其余声明范围内通过。provider adapter 需调用方提供传输、异步运行时、plugin host 或持久 session store。

七、治理与宿主状态

如果 Agent 住在一个外部 Python 服务里,策略、工具授权、检查点、审计事件、人工审批都要跨进程重新建立,宿主状态和凭证也可能要复制或委托。

如果循环就在 Lua 宿主里,宿主状态、凭证和策略决策可以靠得更近。这减少了一种边界穿越,但不自动等于安全、合规或资源可控。

八、代价与不适用场景

Lua SDK 的当前范围:

  • 11 组向量通过;
  • core tests;
  • 公共 API 快照;
  • 远程 lua-conformance CI;
  • 源码 tag lua/v0.8.0;
  • 三个 partial 面;
  • provider adapter 需调用方提供传输;
  • 不是包注册表发布;
  • 不宣称异步运行时;
  • 不是 plugin host;
  • 不宣称持久 session store;
  • 不是通用 PII 合规;
  • 不宣称生产可用。

如果你需要 LuaJIT/OpenResty/Redis 支持、包注册表安装、异步 streaming、provider adapter、plugin host 或持久 session store,这个 SDK 不是答案。

九、结论

Lua 不需要变成 Python,才能用 Agent。

它需要的是一个能在宿主进程里受治理地运行、依赖面小、边界清楚的 Agent 循环。

PRAXO-CORE 的答案是:原生模块、table/function 设计、标准库 only、Lua 5.4 边界、明确 partial、把限制写进 parity 清单。

仓库:https://github.com/axisvela/praxo-core
Lua 源码:https://github.com/axisvela/praxo-core/tree/main/language/lua
Lua 文档:https://axisvela.github.io/praxo-core/languages/lua/
语言矩阵:https://github.com/axisvela/praxo-core/blob/main/spec/languages.md

本文地址
最后修改
星期六, 十一月 21, 2026 - 17:57
Article
↑