Agents
An agent is an AI assistant with a defined purpose, a set of tools it can use, and an optional model override. Every agent you create lives in the sidebar of the Synapse UI and can be chatted with directly or embedded in an orchestration.
Creating an agent
Open the Agents tab and click + New Agent. A form panel slides in with the following fields:
| Field | Purpose |
|---|---|
| Name | Display label shown in the sidebar |
| Description | One-liner explaining what the agent is for — also used by Delegate agents when routing |
| Type | One of conversational, code, orchestrator, or delegate (see below) |
| System Prompt | The agent's persistent instructions. There's a Generate button that turns a short brief into a full system prompt |
| Model | Per-agent model override. Leave on (default) to inherit the global default from Settings → Models |
| Max Turns | ReAct turn limit (default 30). Lower for cheap agents, raise for deep-research ones |
| Tools | Tick the tools this agent may use. all is the everything-on shortcut |
| Repos | (Code agents) Tick the code repositories this agent may search. Configure repos under Settings → Repos |
| DB Configs | (Code agents) Tick the databases this agent may query. Configure connections under Settings → DBs |
| Orchestration | (Orchestrator agents) Pick the orchestration this agent runs |
| Delegate Agents | (Delegate agents) Tick a subset of agents this delegate may route to. Leave empty to allow routing to all |
Click Save. The agent appears in the sidebar and is immediately usable in chat and orchestrations.
Agent types
When you create an agent, you choose one of the following types that determines how it behaves.
Conversational agents are general-purpose assistants. They maintain a full multi-turn conversation history and are the right choice for most tasks — research, writing, analysis, support.
Code agents are software engineering assistants. They have access to indexed code repositories and configured databases, and can search code semantically before reading or editing files. Assign repos and DB configs to a code agent in its settings.
Orchestrator agents wrap an orchestration DAG. Sending a message to an orchestrator agent triggers the linked orchestration rather than a free-form conversation. This lets you expose a complex multi-step pipeline as a simple chat interface.
Delegate agents are dynamic routers. Instead of answering directly, a delegate agent inspects the incoming query, reasons about which of its configured sub-agents is best suited to handle it, and delegates the task — running the chosen sub-agent's full ReAct loop autonomously before returning the result. Use delegate agents when you want a single entry point that intelligently fans out to a pool of specialised agents.
The ReAct loop
Every agent except orchestrators processes messages using the ReAct (Reason + Act) pattern:
- The user message is combined with the system prompt, the tool list, and conversation history, then sent to the LLM.
- The LLM produces a response that may include one or more tool calls.
- If there are tool calls, Synapse executes them and feeds the results back to the LLM.
- This repeats until the LLM produces a final response with no tool calls — or until Max Turns is reached.
Each iteration of this loop is one turn. The default limit is 30 turns per conversation message. You can lower this for simple agents to keep costs predictable, or raise it for agents that need to do deep research with many tool calls.
Advanced: stored agent JSON (conversational)
{
"id": "agent-abc123",
"name": "Research Agent",
"description": "Deep research using web browsing and code search",
"type": "conversational",
"tools": ["all"],
"repos": [],
"db_configs": [],
"system_prompt": "You are a research specialist...",
"orchestration_id": null,
"delegate_agent_ids": [],
"model": "claude-3-5-sonnet-20241022",
"max_turns": 30
}
Field reference
type — one of conversational, code, analysis, orchestrator, or delegate.
tools — ["all"] gives access to every available tool. Alternatively, list specific tool names such as ["browser_navigate", "vault_write"]. MCP tools are prefixed with the server name, e.g. github__create_issue.
repos — list of repo IDs this agent can search (code agents). Configure repos under Settings → Repos.
db_configs — list of database config IDs this agent can query. Configure connections under Settings → DBs.
orchestration_id — for orchestrator-type agents: the ID of the orchestration to run.
delegate_agent_ids — for delegate-type agents: an optional list of agent IDs this delegate may route to. Leave empty ([]) to allow routing to any available agent.
model — per-agent model override. Leave null to use the global default set in Settings → Models.
max_turns — per-agent ReAct turn limit. Leave null to use the global default of 30.
Orchestrator agents
Orchestrator agents bridge the chat interface and the orchestration engine. When you link an agent to an orchestration, any message sent to that agent becomes the initial input for the orchestration run. The full step-by-step execution happens under the hood, and the final output is returned as the agent's response.
In the agent editor, set Type to orchestrator and pick an orchestration from the Orchestration dropdown. This is useful for exposing pipelines to end users who shouldn't need to know about the underlying orchestration structure.
Advanced: stored agent JSON
{
"type": "orchestrator",
"orchestration_id": "orch-abc123"
}
Delegate agents
Delegate agents provide dynamic, LLM-driven task routing across a pool of specialised agents. When a message arrives, the delegate agent receives a roster of available sub-agents — their names, descriptions, types, and tools — injected into its context alongside a synthetic delegate_to_agent tool. The LLM reasons about which sub-agent is the best match for the task and calls that tool; Synapse then runs the chosen sub-agent's full ReAct loop and returns its result.
In the agent editor, set Type to delegate. The Delegate Agents field appears: leave it empty to allow routing to any agent in your workspace, or tick a specific subset to restrict the pool.
Advanced: stored agent JSON
{
"type": "delegate",
"delegate_agent_ids": ["agent-researcher", "agent-coder", "agent-analyst"]
}
Key behaviours:
- Delegate agents start fresh on each invocation — no conversation history is carried between messages, consistent with orchestrator agents.
- A delegate agent cannot route to itself, to other delegate agents, or to builder agents.
- The delegate may synthesise a response from multiple sub-agent results if the task warrants it.
- Delegate agents can be used directly in chat or as an Agent step inside an orchestration, giving you dynamic routing within a deterministic pipeline.