TurfAI Developer DocsAI-app patterns
Vendor-neutral patterns for building AI applications, mapped onto TurfAI.
Learn the recurring patterns behind good AI applications, and the TurfAI primitive that implements each one. Each section explains a pattern in general terms, then links to the TurfAI page. If you've built on other agent frameworks, use the table below to translate.
| Pattern | What it solves | TurfAI primitive |
|---|---|---|
| ReAct agent | Let an LLM decide and act in a loop | Agent |
| Tool use | Give the model real-world capabilities | Tool registry + integrations |
| RAG | Ground answers in your own data | Knowledge Base & RAG |
| Multi-agent orchestration | Split work across specialists | Squads |
| Human-in-the-loop | Keep a person in control of risky steps | HITL pause/resume |
| Governance / PII | Don't leak sensitive data to the model | Data Shield |
| Deterministic control flow | Branch and gate without an LLM | decision / wait task types |
Agents and the ReAct loop
An agent is an LLM given a goal and a set of tools, run in a loop: it reasons about what to do, acts by calling a tool, observes the result, and repeats until it can answer — or until it hits an iteration budget. This is the ReAct (Reason + Act) pattern.
An autonomous agent loops on tool calls, treats each result as ground truth, and pauses for a human at checkpoints. Adapted from Anthropic's "Building effective agents".
Source: Anthropic ↗In TurfAI, the loop is bounded by max_iterations (default 10) and temperature
(default 0.3). Every run returns a trace so you can see exactly which tools fired and why.
See Agents.
Best practices that carry over: keep goals specific; give an agent the fewest tools it needs; prefer deterministic workflow nodes for steps that don't need reasoning; always inspect the trace when debugging.
Start simple, add agents last. Prefer a fixed workflow for predictable, auditable processes; reach for an agent only for open-ended work where you can't predict the number of steps up front — and wrap it in HITL and governance guardrails to bound cost and compounding errors. Guidance adapted from Anthropic's "Building effective agents".
Tool use
Agents are only as capable as their tools. TurfAI ships a built-in tool registry (classify, extract, search/RAG, summarize, send email, fetch URL, fetch Drive file, generate text), and you extend reach with custom REST calls and MCP servers. Restrict each agent to the tools its job requires. See Integrations.
RAG (retrieval-augmented generation)
LLMs don't know your private documents and will confidently make things up. RAG fixes this: index your documents as vector embeddings, retrieve the most relevant chunks for a question, and pass them to the model as context so its answer is grounded and cites sources.
The TurfAI Knowledge Base does this end to end. See Knowledge Base & RAG.
Multi-agent orchestration
Some tasks are too big for one agent. Split them across specialists that share intermediate results. The two common coordination patterns:
- Sequential — a fixed pipeline (research → write → review), each step reading the previous step's output.
- Hierarchical — a manager agent receives the whole goal and delegates to workers dynamically.
TurfAI Squads support both, with a shared blackboard and an audit trail of every write.
Human-in-the-loop (HITL)
Automation shouldn't make irreversible or high-stakes decisions alone. HITL pauses a run at a checkpoint, surfaces what's pending, and resumes once a human approves or supplies input.
In TurfAI a paused run reports awaiting_user_input with a correlation_token. You resume it
with POST /workflow-executions/:id/resume. See the HITL guide.
Governance and PII
In an enterprise, the model must not see raw PII, and every AI call must be auditable. Data Shield tokenizes detected PII before a request reaches the LLM and restores it in the response, writing an immutable audit row (entity counts, never raw values). Combine it with credentials (encrypted at rest) and step-up auth for sensitive operations.