Agents

An Agent is an actor that runs turns against an LLM with access to TulipFarm's tools. Normal chat is the built-in harness; Agents are the custom actors you create by describing them to chat, such as "create a support agent that answers customer questions and files tickets."

What an agent is made of

Each agent the assistant builds is a single AGENT.md file in the soul: YAML frontmatter plus a markdown body. The body is the agent's system prompt; the frontmatter is its metadata. You do not write this — it is what the assistant produces from your description, shown here so you know what each setting means when you ask for it.

---
label: Support
domain: customer-success
description: Handles inbound customer questions.
model: auto
autonomy: supervised
---

You are the support agent. You answer customer questions using the
knowledge base and create tickets as resources when follow-up is needed.

Names are flat and kebab-cased. domain is display-only — it groups agents in the UI but grants no special access. Agents are loaded into the registry at startup.

Autonomy: how much an agent can do unsupervised

The autonomy field controls when an agent must pause for human approval before taking a real-world or data action. It takes one of four values:

When an approval-required agent calls a tool that requires approval, the turn pauses and emits an approval request; it resumes only once a human resolves it. This is the oversight mechanism that makes autonomous operation safe.

Autonomy also influences model selection: see LLM tiers.

What agents may touch

Editing the soul — creating or changing an agent, skill, or schema — is never gated. The autonomy gate applies only to actions on the outside world and your data. In V1 every agent has access to the full tool set; there is no per-agent tool restriction yet.

Guardrails

Independent of autonomy, every turn runs through three guard stages configured in soul/guardrails.yaml: input (before the model sees the message), tool-call (before each tool executes), and output (after the model responds). Guards use pattern matching — no extra LLM required. If guardrails.yaml is absent or invalid, the instance falls back to built-in safe defaults.

Creating agents

Ask the assistant — "create a support agent", "make me an agent that triages bugs". The assistant loads agent-forge, asks what the agent should do and how much autonomy it gets, then writes the AGENT.md and commits it to the soul. There is no approval step, and the agent is selectable as soon as it is built. The web UI lists your agents and shows each one's prompt; to change an agent, ask the assistant to edit it.