Tactus in a Nutshell

Troubleshooting

Common Errors

"Agent not found"

Agent referenced but not defined:

-- Wrong
researcher()

-- Right: Define the agent (assignment-based) first
researcher = Agent { model = "openai/gpt-4o-mini", system_prompt = "...", tools = {done} }
researcher()

"Provider not specified"

Agent missing a provider (or a provider-prefixed model). The simplest fix is to use model = "openai/...":

-- Wrong
worker = Agent { system_prompt = "...", tools = {done} }

-- Right
worker = Agent { model = "openai/gpt-4o-mini", system_prompt = "...", tools = {done} }

"Required output field missing"

Procedure didn't return required field:

Procedure {
  output = {result = field.string{required = true}},
  function(input)
    -- Wrong: no return
    Log.info("Done")

    -- Right: return all required fields
    return {result = "completed"}
  end
}

"Tool 'name' not available"

Tool not enabled for that agent turn:

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

search = Tool { description = "Search", input = {query = field.string{required = true}}, function(args) return "..." end }
worker = Agent { model = "openai/gpt-4o-mini", tools = {done} }
-- search exists, but worker can't call it

-- Right
worker = Agent { model = "openai/gpt-4o-mini", tools = {search, done} }

Debugging Checkpoints

View execution trace:

tactus trace-list
tactus trace-show <trace-id>

API Issues

Rate limits

Add delays or reduce parallelism.

Timeouts

Check network connectivity. Consider retry logic.

Invalid API key

Verify key in config or environment:

echo $OPENAI_API_KEY
cat .tactus/config.yml

Performance Issues

Slow execution

High costs

Test Failures

"Step not found"

Custom step not defined or typo in step text.

"Specification failed"

Check that agent behavior matches spec. Run with verbose output:

tactus test procedure.tac --verbose