Documentation
¶
Overview ¶
Package lua exposes hex/ai's default agent to Lua scripts via a gopher-lua module named "agent".
The module is loaded by a service provider that resolves the shared *hex/lua.Environment from the container (bound by hex/lua/provider), resolves the default ai.Agent, and calls env.PreloadModule("agent", ...). Consumers add the provider to their boot.go alongside the base Lua provider:
provider.Lua(), // hex/lua/provider provider.LuaAI(), // hex/ai/lua/provider — this package
After boot, any Lua script running in the environment can:
local agent = require("agent")
-- Simple ask, no conversation history:
local response, err = agent.ask("session-1", "Summarise this incident.")
-- With options — subset of tools, temperature, max tokens:
local response, err = agent.ask(thread_ts, event.text, {
tools = { "get_incident", "post_slack" },
temperature = 0.3,
max_tokens = 500,
})
-- Introspection:
for _, name in ipairs(agent.tools()) do
print("available:", name)
end
-- Reset a conversation:
agent.forget(thread_ts)
Response tables include:
response.text string -- flattened assistant text response.usage.input_tokens int response.usage.output_tokens int response.usage.total_tokens int response.model string -- (best-effort from steps)
Errors return (nil, "message").
Concurrency:
*lua.LState is not thread-safe. When multiple goroutines may call agent.ask() against the same environment (event bus handlers, web request handlers, etc.), pass Bindings.Mutex so this package guards the Generate call. See PLAT-3545 notes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bindings ¶
type Bindings struct {
// Agent is the fantasy.Agent to call. Required.
Agent ai.Agent
// Registry is consulted for tool introspection (agent.tools()) and
// for validating ActiveTools passed from Lua. Optional; when nil
// the module trusts whatever tool names Lua supplies.
Registry ai.ToolRegistry
// Store persists multi-turn conversation history keyed by the
// first argument to agent.ask. Optional; when nil each call is a
// fresh single-turn interaction (Prompt only, no Messages).
Store ai.ConversationStore
// Mutex, when non-nil, is locked around every Generate call. Use
// this to serialise concurrent agent.ask invocations that share
// the same *lua.LState (event bus subscribers, web handlers).
Mutex *sync.Mutex
// Context, when non-nil, is used for every agent call. Defaults
// to context.Background(). Consumers who need per-call ctx (e.g.
// from an HTTP request) install a fresh Bindings per request or
// stash the ctx in the LState registry themselves.
Context context.Context
}
Bindings configures the 'agent' module. Constructed and installed by hex/ai/lua/provider; callers who want to wire the module manually (outside the provider lifecycle) build one directly and call Loader.
Source Files
Directories