Skip to content

Core Concepts

tama has a small number of concepts that stack. Each one is built from the one before it, so you can learn them in order — from the simplest thing you can write to the whole system running in production.

This page is the map. Each concept links to its own page for the detail.

Underneath everything there are only two ideas:

  1. The react atom — a loop of call the model → run a tool → call the model → … until the model says it’s done. Every LLM call in tama happens inside one of these. There is no other way to invoke a model.
  2. Composition — wiring atoms together. There are two ways: run them in sequence (an FSM, where each step’s result decides what runs next) or at the same time (parallel, collecting all results). Everything else is a named shorthand for one of these.

That’s the whole engine. The concepts below are just increasingly convenient ways to express those two ideas — and then to package, deploy, and observe them.

#ConceptOne lineIt’s made of
1SkillA tool. Deterministic, no LLM.code
2AgentA leaf that reasons, using skills.react atom + skills
3WorkflowOrchestration over agents. Routes, doesn’t reason.agents composed by FSM / parallel
4CompositeNamed workflow shapes (critic, reflexion, …).sugar over workflows
5AppThe deployable unit: one project, one container.agents + workflows + tama.toml
6RunOne execution = one trace = one A2A task.an app, executing

Cross-cutting, once you have the ladder: data flow (how input and results move), models & roles, tracing, and serving.


The simplest thing in tama. A skill does one deterministic job and involves no model: fetch a URL, run a shell command, read a file. It lives in skills/<name>/SKILL.md.

skills/
search-web/SKILL.md ← a tool: web search

An agent can only use a skill if it declares it. Skills are the hands; the agent is the brain. → Skills

An agent is the smallest thing that thinks. It’s a react atom with a system prompt and a list of skills it may use. It lives in agents/<name>/AGENT.md.

Two leaf patterns:

  • oneshot — a single model call. Input → model → output. No tools.
  • react — the tool-use loop. The model calls tools, sees results, and loops until it calls finish.
# agents/researcher/AGENT.md
name: researcher
pattern: react
call:
uses: [search-web]

An agent is a leaf: it reasons, it does not orchestrate other agents. The moment you want to coordinate several agents, you’ve reached a workflow. → Agents

A workflow wires agents together. It routes; it doesn’t reason. It lives in workflows/<name>/WORKFLOW.md. There are three primitive shapes:

  • fsm — a state machine. Each agent finishes with a routing word (finish(key)); the state table maps that word to the next agent. This is the escape hatch — any control flow can be written as an FSM.
  • scatter — map → run a worker on each item in parallel → reduce the results.
  • parallel — run a fixed set of agents at once, collect all their outputs.
# workflows/pipeline/WORKFLOW.md
name: pipeline
pattern: fsm
initial: research
states:
research: reviewer
reviewer:
- approved: ~ # stop
- retry: research # loop back

Workflows nest: a workflow can reference other workflows as freely as agents. → Workflows

Most useful agent patterns are just specific FSMs. Rather than write the state table every time, tama ships them as named composite patterns — sugar that desugars to the primitives above:

CompositeShape
criticdraft → critique → refine
constitutionalgenerate → critique → revise
chain-of-verificationgenerate → verify → check → revise
debateposition-a → position-b → judge
reflexionact → evaluate → (loop until pass)
plan-executeplan → execute → verify → (loop until pass)
best-of-nrun N variants in parallel → judge picks the best

You name an agent for each role; tama builds the FSM.

# workflows/blog-writer/WORKFLOW.md
name: blog-writer
pattern: critic
draft: draft
critique: critique
refine: refine

They add no new power — anything a composite does, you can write by hand as an fsm. They just save you the wiring. → Composites

An app is a whole project: your agents/, workflows/, and skills/ plus a tama.toml. It’s what tama brew turns into a single container.

Crucially, the app decides what it exposes. You may have dozens of nested workflows, but only the ones you list in expose become callable from outside — everything else is private machinery. Composition is free; publishing is a deliberate choice.

tama.toml
[project]
name = "deep-research"
expose = ["research-pipeline"]

→ Apps

A run is a single execution of one exposed agent/workflow on one input. A run is a trace: it has an id, and everything that happens inside it — every workflow, agent, model call, and tool call — nests under that id in your observability backend. When the app is served, one run is exactly one A2A task.

run: research-pipeline ← the run / A2A task
fsm: research-pipeline ← a workflow
scatter: research ← a nested workflow
map ← a leaf agent
llm: react_1 ← a model call

→ Runs