Preface

Welcome to Learning Tactus.

Tactus is a programming language for building AI agents. You define agents, give them tools, and write procedures that orchestrate their work. The runtime handles the hard parts—durability, checkpointing, and human-in-the-loop—so you can focus on what your agents should do.

Formats

If you’ve experimented with tool-using agents, you’ve probably felt the magic: plug a tool into a chat assistant (Cursor, Claude.ai, anything that speaks MCP), describe what you want, and the model can use it—while you watch.

That’s great for interactive sessions. The problem starts when you want the same tool access in an unattended workflow: background jobs, pipelines, or agents that run overnight. Useful tools are powerful—and power cuts both ways. An email tool can send the right message… or the wrong message to the wrong person. If you rely on the model to always call the right tool at the right time with the right inputs, you’re giving a monkey a razor blade and hoping for the best. That might work a few times, but it isn’t a sustainable way to build something you can trust.

This book is for people who want to keep the magic, but make it safe to run unattended.

We’ll do that with programmatic guardrails: explicit tool access, approval gates before risky actions, durable execution when workflows pause, and tests/evaluations that measure reliability.

Under the hood, Tactus builds on DSPy: typed signatures, modules, and optimizers for working with LLMs. Tactus adds a higher-level DSL with durable execution, sandboxing, and human-in-the-loop primitives on top. You don’t need to know DSPy to get started—we’ll begin with Tactus’s simplest, highest-level constructs, and only go deeper when you’re ready.

Who This Book Is For

This book is written for AI/ML practitioners who:

  • Have built tool-using agents with Python scripts, LangChain, or similar tools
  • Have seen agents “mostly work” and then suddenly call the wrong tool (or use the right tool at the wrong time)
  • Want programmatic guardrails: controlled tool access, approvals, and durable workflows you can resume safely
  • Want a language designed for agent orchestration, not just model calls

You don’t need to know Lua—we’ll teach you everything you need. You should be comfortable with basic programming concepts (variables, loops, functions) in any language.

What You’ll Learn

By the end of this book, you will:

  1. Understand the durability problem that Tactus solves and why traditional frameworks fall short
  2. Write your first Tactus procedures with agents, tools, and state management
  3. Build robust agent loops that handle real-world conditions
  4. Add human-in-the-loop approval gates and input requests
  5. Write specs and evaluations from day one—BDD for behavior, evaluations for reliability
  6. Build complete examples that demonstrate production-ready patterns

How to Use This Book

This book is designed to be read sequentially. Each chapter builds on the previous one.

  • Part I lays the foundations and gets you set up: what Tactus is, plus transparent durability, everything-as-code, and a quick install so you can run the examples.
  • Part II builds a useful agent workflow by iteratively extending a single running example: typed I/O, tools, state/idempotency, loops, and HITL.
  • Part III is about guardrails: safety and information security for “agents with power.” It begins by naming the levers of control you can pull beyond prompt engineering, then shows how to enforce boundaries with capability control, sandboxing, isolation boundaries, and secretless execution.
  • Part IV is about reliability at scale: behavior specs and evaluations to make sure the workflow keeps doing the right thing over time.
  • Part V ends with complete examples you can adapt.

Every code example in this book is a runnable .tac file. You can find them in the code/ directory, organized by chapter.

Conventions Used

Code examples are shown in blocks like this:

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

greeter = Agent {
    model = "openai/gpt-4o-mini",
    tool_choice = "required",
    system_prompt = [[You are a friendly assistant. When asked to greet someone, provide a warm, friendly greeting.

When you're done, call the done tool with reason set to your greeting message. Do not use emojis.]],
    initial_message = "Please greet the user with a friendly message",
    tools = {done},
}

When we show terminal commands, they look like this:

tactus run hello.tac

Version

Built and tested against Tactus v0.42.3 (commit 9cd20d889c31).

Let’s Begin

Turn the page to learn why AI agents need a language of their own.