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
- Check model selection (gpt-4o-mini faster than gpt-4o)
- Review token usage
- Consider caching or
Step.checkpoint(...)for expensive deterministic work
High costs
- Use smaller models for simple tasks
- Reduce max_tokens
- Review tool call frequency
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