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.
The mental model
Section titled “The mental model”Underneath everything there are only two ideas:
- 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.
- 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.
The ladder
Section titled “The ladder”| # | Concept | One line | It’s made of |
|---|---|---|---|
| 1 | Skill | A tool. Deterministic, no LLM. | code |
| 2 | Agent | A leaf that reasons, using skills. | react atom + skills |
| 3 | Workflow | Orchestration over agents. Routes, doesn’t reason. | agents composed by FSM / parallel |
| 4 | Composite | Named workflow shapes (critic, reflexion, …). | sugar over workflows |
| 5 | App | The deployable unit: one project, one container. | agents + workflows + tama.toml |
| 6 | Run | One 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.
1. Skill — a tool
Section titled “1. Skill — a tool”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 searchAn agent can only use a skill if it declares it. Skills are the hands; the agent is the brain. → Skills
2. Agent — a leaf that reasons
Section titled “2. Agent — a leaf that reasons”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 callsfinish.
# agents/researcher/AGENT.mdname: researcherpattern: reactcall: 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
3. Workflow — orchestration over agents
Section titled “3. Workflow — orchestration over 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.mdname: pipelinepattern: fsminitial: researchstates: research: reviewer reviewer: - approved: ~ # stop - retry: research # loop backWorkflows nest: a workflow can reference other workflows as freely as agents. → Workflows
4. Composite — named workflow shapes
Section titled “4. Composite — named workflow shapes”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:
| Composite | Shape |
|---|---|
critic | draft → critique → refine |
constitutional | generate → critique → revise |
chain-of-verification | generate → verify → check → revise |
debate | position-a → position-b → judge |
reflexion | act → evaluate → (loop until pass) |
plan-execute | plan → execute → verify → (loop until pass) |
best-of-n | run N variants in parallel → judge picks the best |
You name an agent for each role; tama builds the FSM.
# workflows/blog-writer/WORKFLOW.mdname: blog-writerpattern: criticdraft: draftcritique: critiquerefine: refineThey add no new power — anything a composite does, you can write by hand as an
fsm. They just save you the wiring. → Composites
5. App — the deployable unit
Section titled “5. App — the deployable unit”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.
[project]name = "deep-research"expose = ["research-pipeline"]→ Apps
6. Run — one execution
Section titled “6. Run — one execution”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
Where to go next
Section titled “Where to go next”- Follow the ladder top to bottom: Skills → Agents → Workflows → Composites → Apps → Runs.
- Then the cross-cutting concept: Data flow — how input and results actually move between agents.
- Or jump to the hands-on Quickstart.