Programming Tactus

Agent Configuration

This chapter describes the stable configuration surface area of the Agent primitive.

An Agent is stateful and multi-turn: it can call tools, accumulate message history, and iterate until done. That flexibility is powerful, but it also means the configuration is where most reliability and safety decisions are made.

Declaring an Agent

Agents are declared at top level using assignment syntax:

local done = require("tactus.tools.done")

lookup_customer = Tool {
  description = "Look up a customer record",
  input = { id = field.string{required = true} },
  function(args)
    return {id = args.id, plan = "pro"}
  end
}

triage_agent = Agent {
  model = "openai/gpt-4o-mini",
  system_prompt = [[
You triage support messages into labels: billing, account, bug, other.
Use lookup_customer when you need account context. Call done when finished.
  ]],
  tools = {lookup_customer, done}
}

Notes:

Provider and Model Selection

Agent declarations typically specify:

In many codebases, you will centralize provider/model choice in environment configuration, and keep the agent declaration focused on:

System Prompt (and Template Variables)

system_prompt is the instruction that frames every agent turn.

Tactus supports template variables inside prompts (for example: {input.customer_id}), so you can parameterize a single agent configuration for different procedure inputs.

Best practice:

Tool Access (and Capability Boundaries)

Tools are an agent's capability boundary.

tools = {...}

The tools field defines the default set of tools and toolsets available to an agent.

You can pass:

Even if an agent has tools, you should often restrict tools per call:

-- Full tools turn
triage_agent({message = "Investigate and gather facts.", tools = {lookup_customer, done}})

-- Summarize / decide with no tools
triage_agent({message = "Summarize findings. No new tool calls.", tools = {}})

This pattern is one of the most effective ways to reduce runaway tool loops and make behavior more testable.

Generation and Execution Parameters

Agents support a small set of generation parameters that you can set on the declaration, and override per call when needed.

Common fields:

Per-call overrides are documented in Chapter 05.

Initial Message

Some workflows benefit from sending an initial_message on the first turn (for example: bootstrapping a plan). Prefer explicit procedure calls when possible; use initial_message only when it simplifies a pattern that is otherwise awkward.