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.
The lifecycle
Section titled “The lifecycle”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 tracedEach stage is described below.
1. Author — the building blocks
Section titled “1. Author — the building blocks”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/…)| Folder | File | Role |
|---|---|---|
skills/ | SKILL.md | A tool. Does one job, deterministically. The agent’s hands. |
agents/ | AGENT.md | A leaf agent. react (tool loop) or oneshot (single call). The brain. |
workflows/ | WORKFLOW.md | A 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.
2. Config — tama.toml
Section titled “2. Config — tama.toml”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.
3. Build — tama brew → a Docker image
Section titled “3. Build — tama brew → a Docker image”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.
4. Serve — the A2A server (tamad)
Section titled “4. Serve — the A2A server (tamad)”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).
5. Execute — the runtime
Section titled “5. Execute — the runtime”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, …).
6. Observe — OpenTelemetry → Langfuse
Section titled “6. Observe — OpenTelemetry → Langfuse”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/otelOTEL_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 agentErrors set the native span status, so a failed run shows red and is filterable. See Tracing & Observability.
End to end: one request
Section titled “End to end: one request”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.