Skip to content

Architecture

This page is the whole system on one screen: what you write, how it’s packaged into a container, how that container serves requests, and how every request is traced. For the conceptual ladder (what each building block is), see Core Concepts.

tama has four stages: author → build → serve → observe.

AUTHOR BUILD SERVE OBSERVE
┌──────────┐ ┌──────────┐ ┌───────────┐ ┌────────────┐
│ skills/ │ │ │ │ tamad │ OTLP │ Langfuse │
│ agents/ │ tama │ Docker │ docker │ (A2A │ ──────► │ (or any │
│workflows/│ brew │ image │ run │ server) │ spans │ OTel │
│ tama.toml│ ───────► │ +tamad │ ─────► │ │ │ backend) │
└──────────┘ └──────────┘ └───────────┘ └────────────┘
you write one artifact one container every run traced

Each stage is described below.


A tama project is just files. Three kinds of building block, each in its own top-level folder:

my-project/
├── tama.toml ← app config
├── skills/
│ └── search-web/SKILL.md ← a tool (deterministic, no LLM)
├── agents/
│ ├── researcher/AGENT.md ← a leaf that reasons (react / oneshot)
│ └── reviewer/AGENT.md
└── workflows/
└── pipeline/WORKFLOW.md ← orchestration over agents (fsm/scatter/…)
FolderFileRole
skills/SKILL.mdA tool. Does one job, deterministically. The agent’s hands.
agents/AGENT.mdA leaf agent. react (tool loop) or oneshot (single call). The brain.
workflows/WORKFLOW.mdA workflow. Routes over agents: fsm, scatter, parallel, or a composite (critic, reflexion, …).

They stack: skills are used by agents; agents are composed by workflows; workflows nest inside workflows. Underneath, every model call happens inside a react atom, and all composition is either sequential (FSM) or concurrent (parallel). Full ladder: Core Concepts.

tama.toml turns a folder of building blocks into an app: it names the project, configures models, and — critically — declares what the app exposes.

[project]
name = "deep-research"
entrypoint = "research-pipeline"
# Only these are callable from outside the container. Everything else
# (helper agents, nested sub-workflows) stays private.
expose = ["research-pipeline"]
[models]
# Named roles agents refer to. A role is `provider:model`.
thinker = "anthropic:claude-sonnet-4-6"
default = "bedrock:anthropic.claude-3-5-sonnet-20241022-v2:0"

You can compose dozens of nested workflows, but publishing one as a callable capability is a deliberate choice — expose is the single line where a human decides what has business value. See tama.toml reference and Models.

tama brew reads tama.toml, scans your skills for declared dependencies, and produces one self-contained Docker image:

tama brew
│
├─ scan skills/ for `depends:` (apt / uv / python)
├─ fetch the tamad runtime binary (linux/amd64)
└─ generate a Dockerfile:
FROM debian:bookworm-slim
RUN apt-get install … (declared deps)
COPY tamad /tamad
COPY agents/ workflows/ skills/ tama.toml /app/
EXPOSE 8080
ENTRYPOINT ["/tamad"]

The output is a normal OCI image. tama’s job ends here — how and where it runs (Kubernetes, ECS, docker run) is not tama’s concern. The image is the artifact. See brew and Deploying.

The container runs tamad, which is server-only: it exposes the app as a single A2A agent over JSON-RPC 2.0. Each exposed agent/workflow becomes an advertised skill on the agent card; each request opens an A2A Task.

one container = one A2A agent
┌──────────────────────────────────────────────────────────┐
│ tamad (HTTP :8080, JSON-RPC 2.0) │
│ │
│ GET /.well-known/agent-card.json → card + skills[] │
│ POST / (SendMessage / GetTask) → A2A Task lifecycle │
│ │
│ message.metadata.skill ─┐ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ route to exposed agent/wf │ │
│ │ open Task (submitted→working)│ │
│ │ run it → completed | failed │ │
│ └─────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
  • One agent, many skills. Skills are the advertised menu; a Task is one invocation with a lifecycle (working → completed | failed).
  • The A2A task id is the run’s trace id, so a task and its trace are the same thing end to end.
  • Protocol handling is a real A2A library (a2a-rs); tama only supplies the routing + execution.

See tamad (A2A server).

Inside a request, runtime::run builds the graph for the named agent/workflow and executes it. One RunContext is threaded by reference through the whole run — no global state:

run(agent, task, trace_id, tracer)
│
├─ Graph::build → resolve agents/workflows by name (local-first, path-keyed)
├─ RunContext → trace_id, app, workspace, model registry, per-run store
└─ exec(root) → dispatch by node type:
Agent → react / oneshot (leaf: calls the model)
Workflow → fsm | scatter | parallel (routes over children)
└ composites desugar to these primitives
  • Graph — a unified, path-keyed node graph; names resolve local-first (a subfolder of the referencing workflow) then global (agents/, workflows/).
  • exec — a single dispatch: leaf agents run the react/oneshot loop; workflows route to children by key. Composites (critic, reflexion, best-of-n, …) build an equivalent FSM/parallel composition and reuse the same executors.
  • Tools — a react agent’s tool calls run through the tool registry (tama_files, tama_http, tama_grep, tama_mem, …).

Every run emits an OpenTelemetry trace over OTLP. Point it at Langfuse (or any OTel backend) with standard env vars — no code change:

OTEL_EXPORTER_OTLP_ENDPOINT=https://<langfuse>/api/public/otel
OTEL_EXPORTER_OTLP_HEADERS='Authorization=Basic <base64(pk:sk)>'

The trace mirrors the execution tree exactly — the run, each workflow (labelled by pattern), each leaf agent, and every model call and tool call nest under one trace:

run: research-pipeline ← the run / A2A Task (trace root)
└─ fsm: research-pipeline ← a workflow
└─ scatter: research ← a nested workflow
├─ map ← a leaf agent (react)
│ ├─ llm: react_1 ← a model call (generation, with token usage)
│ └─ tool: tama_http ← a tool call
└─ reduce ← a leaf agent

Errors set the native span status, so a failed run shows red and is filterable. See Tracing & Observability.


Putting it together — the journey of a single call:

client ──SendMessage(skill="research-pipeline", text)──► tamad
│ open A2A Task (id = trace_id)
▼
runtime::run
│ Graph::build + RunContext
▼
exec: fsm → scatter → react agents
│ model + tool calls
┌──────────────────┼───────────────────┐
▼ ▼
OTLP spans → Langfuse Task → completed(output)
│
client ◄────────────────── A2A Task (completed, result) ────────────────────┘

One request = one A2A Task = one traced run. That identity is the spine the whole architecture hangs on.