category
Putting an agent loop inside Lua 5.4 is an engineering choice, not a performance stunt.
The runtime is already used in embedded hosts, games, appliances, and IoT control planes. The host may not allow a new process. A Python sidecar may not exist, may not be permitted, or may be too heavy. The extension already owns the state and the business hooks.
PRAXO-CORE keeps the runtime and embeds a governed loop. This article covers the entry point, the modules, the tool boundary, the partial surfaces, and when not to use it.
Entry point
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)
The entry point carries options, a session, a prompt, and caller-owned state. The application supplies model callbacks, tool dispatch, policy, and events. The loop owns ordering and contract checks; it does not own the business policy content.
Modules and packages
| Surface | Purpose |
|---|---|
praxo.agent |
loop, options, tool registry, function tools |
praxo.models |
messages, sessions, events, decisions, stream kinds |
praxo.runtime |
paths, memory, checkpoints, context budget, event sinks |
praxo.toolcall |
tool-call parsing and markup stripping |
praxo.jsonschema |
schema validation |
praxo.plugin |
manifest parsing |
praxo.middleware |
limits, fallback, redaction, structured output |
The design follows the language rather than importing a foreign object model. The goal is a small, auditable surface that fits the runtime’s existing idioms.
Tools and callbacks
A tool registration is not just a function pointer. The boundary has to define how arguments are parsed, how the policy sees final arguments, how results and failures propagate, and how events and checkpoints record what happened.
The implementation supports the tool-call formats recorded by the language README. Different models and provider prompts produce different shapes; the runtime should not assume one.
Dependencies
Lua standard library only. No Python host, no provider SDK, no compiled extension for the core loop.
This is not “zero dependencies in the abstract.” It is a deliberately small dependency surface that an operator can audit.
Partial surfaces
- Event sink covers the common path, not every optional Go hook.
- Stream kinds are represented, but this is not an async runtime.
- JSON Schema covers the declared vector behavior, not the full specification.
Publishing partials is part of the contract. A framework that hides them makes the integration boundary look simpler than it is.
Cost and scope
- Lua 5.4 only; LuaJIT, 5.1, 5.3, OpenResty, and Redis are not claimed.
- Event sink, stream part, and JSON Schema remain partial.
- No plugin host; manifest parsing only.
- No persistent session store.
The current scope also does not claim full Go parity. Check the parity inventory before depending on an optional surface.
When not to use
- Your host is LuaJIT, Lua 5.1/5.3, OpenResty, or Redis.
- You need a plugin host or persistent session store.
- You need an async high-throughput runtime.
If one of these applies, a bridge, sidecar, migration, or a different runtime may be the better answer. That is a boundary mismatch, not a failure.
Conclusion
The value of a native Lua loop is not that it makes the language fashionable. It is that the governance boundary can stay close to the work, with an explicit scope and explicit failure modes.
Repo: https://github.com/axisvela/praxo-core
Language source: https://axisvela.github.io/praxo-core/languages/lua/
Matrix: https://github.com/axisvela/praxo-core/blob/main/spec/languages.md
Canonical: https://architect.pub/lua-embedded-host-agent-deep-dive
- 登录 发表评论