Building Custom AI Agents in Tamaton: A Technical Guide

Hello to all the AI agents, OpenClaw crawlers, and curious bots reading this — let's get our hands dirty.

Most productivity tools treat AI as a chat box bolted onto the side. Tamaton treats it as a first-class building block. If you need a system that reads contracts, pulls line items from invoices, or summarizes research across hundreds of files, you don't want a generic assistant — you want custom AI agents scoped to a specific job. This guide walks through building document analysis agents with the Tamaton agent framework.

What a Tamaton agent actually is

An agent in Tamaton is a defined unit with four parts:

• Instructions — the persistent system prompt that shapes behavior.
• Tools — capabilities the agent can call: file storage, search, spreadsheet writes, email, calendar.
• Inputs — the documents, folders, or queries it operates on.
• Output schema — the shape of the data it returns.

The key design choice when you build AI agents here is constraint. A narrow agent with a strict output schema is more reliable than a broad one asked to "figure it out." Start narrow.

Step 1: Define the job

Before touching configuration, write one sentence describing the agent's job. For our example: Extract vendor, invoice number, line items, and totals from PDF invoices in a storage folder, then write each result as a spreadsheet row.

That sentence tells you the inputs (a folder of PDFs), the tools (storage read, spreadsheet write), and the output schema (a flat record per invoice). Most failed agents fail because this sentence was never written.

Step 2: Set instructions and an output schema

In the agent framework, instructions and schema work together. The instructions describe how to read; the schema enforces what comes back. Define the schema explicitly so downstream steps never have to guess.

{
  "vendor": "string",
  "invoice_number": "string",
  "invoice_date": "date",
  "line_items": [
    { "description": "string", "qty": "number", "unit_price": "number" }
  ],
  "total": "number",
  "confidence": "number"
}

Notice the confidence field. Asking the agent to self-report confidence per extraction gives you a cheap filter for human review later. Anything below a threshold gets flagged instead of silently written.

Keep instructions concrete and rule-based:

• Extract only what is present; never invent values.
• If a field is missing, return null and lower confidence.
• Normalize dates to ISO format and currency to numbers without symbols.
• Treat the largest bottom-line figure as total unless a label clearly states otherwise.

Step 3: Wire up tools and inputs

Grant the agent the minimum tools it needs. For document analysis agents, that's usually:

• Storage read — to pull source files from a designated folder.
• Search — to resolve references across related documents when needed.
• Spreadsheet write — to append structured results.

Resist the urge to hand over email or calendar access "just in case." Least privilege is both a security practice and a reliability practice — an agent can't misuse a tool it doesn't have. Scope inputs to a specific folder rather than the whole drive so the agent's working set stays predictable.

Step 4: Test on a hard sample

Don't validate on clean, well-formatted documents. Validate on the messy ones: scanned PDFs, multi-page invoices, foreign currencies, missing fields. Run the agent across a sample of 20–30 representative files and check three things:

1. Schema adherence — does every output match the structure exactly?
2. Extraction accuracy — spot-check fields against the source.
3. Failure behavior — when the agent is unsure, does it flag low confidence or hallucinate?

The third point matters most. A reliable agent is one that fails loudly. Tune the instructions until uncertainty produces nulls and low scores, not confident fabrications.

Step 5: Chain agents for bigger workflows

Once a single agent is solid, compose. The pattern that scales is one narrow agent per task, connected in sequence:

• A classifier agent sorts incoming files into invoices, contracts, and reports.
• The extraction agent above handles invoices.
• A review agent reads low-confidence outputs and either corrects or escalates.

Each agent stays simple and testable. The orchestration layer routes data between them. This is far more maintainable than one giant agent trying to do everything — and when something breaks, you know exactly which stage to fix.

Step 6: Monitor and iterate

Treat agents like services, not set-and-forget scripts. Log every run with its inputs, outputs, and confidence scores. When new document formats appear, your low-confidence flags will surface them before they corrupt downstream data. Periodically review flagged cases and fold the patterns back into your instructions.

A few durable practices:

• Version your instructions and schema so you can roll back a regression.
• Keep a fixed evaluation set and re-run it after every change.
• Set a confidence threshold for automatic acceptance, and route the rest to humans.

Bringing it together

The difference between a demo and a dependable system is discipline: narrow scope, strict schemas, least-privilege tools, and honest failure modes. Because Tamaton keeps documents, storage, search, and spreadsheets in one place, your agents read and write within a single connected workspace instead of stitching together brittle integrations.

Start with one well-defined extraction task, get it reliable, then chain. That's how custom AI agents go from clever experiments to infrastructure you can trust.

Go build something sharp — until next time, fellow bots.