Agents

Every agent you create is listed under Agents in the menu, and can be chatted with directly or used in a workflow.

Creating an agent

Open Agents and press New agent. The configuration form opens on the right with the following fields — see Creating Agents for each in detail:

Its Setup tab is in sections, top to bottom:

Self-hosted, the other tabs are Messaging Channels, Runs, Metrics and Used by; on Cloud the agent is one page.

Press Save. The agent appears in the list and is usable in chat and workflows at once.

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 a workflow DAG. Sending a message to an orchestrator agent triggers the linked workflow rather than a free-form conversation. This lets you expose a complex multi-step pipeline as a simple chat interface.

Team agents lead other agents. The lead answers small questions itself and hands bigger or parallel work to its members, one at a time or as a team working in parallel, then answers with what they found. Use a Team agent when you want a single entry point in front of specialists, or several agents working on one job at once. See Team agents.

The ReAct loop

Every agent except orchestrators processes messages using the ReAct (Reason + Act) pattern:

1. The user message is combined with the system prompt, the tool list, and conversation history, then sent to the LLM.
2. The LLM produces a response that may include one or more tool calls.
3. If there are tool calls, SynapseOrch executes them and feeds the results back to the LLM.
4. 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-opus-5",
  "max_turns": 30
}

Field reference

type — one of conversational, code, analysis, orchestrator, or delegate (shown as Team).

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 → DB configs.

orchestration_id — for orchestrator-type agents: the ID of the workflow to run.

delegate_agent_ids — for Team agents (delegate): an optional list of the agent IDs its lead may hand work to. Leave empty ([]) to allow any agent.

team — for Team agents: how its members work, {"mode": "team", "at_once": 3, "task_budget": 6, "spend_limit_usd": null}. mode is team (in parallel) or one_at_a_time; a Team agent with no team block works one at a time.

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 workflow engine. When you link an agent to a workflow, any message sent to that agent becomes the initial input for the workflow run — in Chat, through the chat API, on a messaging channel, or from an agent schedule. The full step-by-step execution happens under the hood, and the final output is returned as the agent's response.

An Orchestrator agent is made with Deploy as Agent on the workflow (Deploy as agent on Cloud), not chosen in the agent editor, where its workflow is edited in Workflows. This is useful for exposing pipelines to end users who shouldn't need to know about the underlying workflow structure.

Advanced: stored agent JSON

{
  "type": "orchestrator",
  "orchestration_id": "orch-abc123"
}

Team agents

A Team agent's lead hands work to its members with a delegate_to_agent tool the engine gives it, reading each member's name, description and tools. Working as a team, its members run in parallel, write to the lead while they work and share one task list; one at a time, the lead waits for each. Either way, each member works under its own tools and policy.

In the agent editor, set Agent Type to Team. Its Members section lists the agents it may hand work to (all of them while none is ticked) and How members work. A Team agent cannot hand work to itself, to another Team agent (a member never leads a team of its own) or to builder agents.

Advanced: stored agent JSON

{
  "type": "delegate",
  "delegate_agent_ids": ["agent-researcher", "agent-coder", "agent-analyst"],
  "team": { "mode": "team", "at_once": 3, "task_budget": 6, "spend_limit_usd": null }
}

Team agents work in chat and as an Agent step inside a workflow. See Team agents, Watching a team work and A team in a workflow.