Skip to main content

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.

Agent types​

When you create an agent, you choose one of four 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.

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, Synapse 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.

Agent schema​

{
  "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,
  "model": "claude-3-5-sonnet-20241022",
  "max_turns": 30
}

type — one of conversational, code, analysis, or orchestrator.

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 only). 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 orchestration to run.

model — per-agent model override. Leave null to use the global default set in Settings → General.

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.

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

This is useful for exposing pipelines to end users who should not need to know about the underlying orchestration structure.

Last updated on