Module agent_script 

Lua scripted agent runtime.

Loads .lua agent scripts at startup, extracts their metadata (name, description, tools, arguments), and provides runtime resolution with a context bridge back into the Rust core (search, get, sources).

Architecture

Agent scripts follow the same sandboxed Lua VM model as connectors and tools, reusing all host APIs from crate::lua_runtime. In addition, agents receive a context table identical to tools:

• context.search(query, opts?) — search the knowledge base
• context.get(id) — retrieve a document by UUID
• context.sources() — list connector status

The agent-specific config from ctx.toml is passed as the second argument to agent.resolve(args, config, context).

Script Interface

Every agent script defines a global agent table:

agent = {
    name = "my-agent",
    description = "Helps with tasks",
    tools = { "search", "get" },
    arguments = {
        { name = "topic", description = "Focus area", required = false },
    },
}

function agent.resolve(args, config, context)
    return {
        system = "You are a helpful assistant.",
        messages = {},
    }
end

Configuration

[agents.script.my_agent]
path = "agents/my-agent.lua"
timeout = 30
search_limit = 5

See docs/AGENTS.md for the full specification.

Structs

AgentDefinition

Metadata extracted from a loaded Lua agent script.

LuaAgentAdapter

Adapter that wraps a Lua AgentDefinition as an Agent trait object.

Functions

doc_response_to_lua 🔒

Convert a document response to a Lua table.

extract_arguments 🔒

Extract argument definitions from a Lua agent.arguments table.

extract_string_list 🔒

Extract a list of strings from a Lua table field.

list_agents

List all configured agents and print their info.

load_agent_definitions

Load all agent scripts from config and extract their definitions.

load_single_agent

Load a single agent script and extract its definition.

lua_result_to_agent_prompt 🔒

Convert the Lua agent.resolve() return value to an AgentPrompt.

register_agent_context_bridge 🔒

Register the context table in the Lua VM for agent scripts.

resolve_agent

Resolve an agent script’s prompt.

run_lua_agent 🔒

Run the Lua agent synchronously on a blocking thread.

scaffold_agent

Scaffold a new agent script from a template.

search_results_to_lua 🔒

Convert search results to a Lua array table.

sources_to_lua 🔒

Convert source statuses to a Lua array table.

test_agent

Test an agent script by resolving its prompt.

truncate 🔒

Truncate a string to fit in a column.