Creating Agents

Creating a new agent

At the top of the Agents screen is New agent, with a menu beside it:

• New agent — opens a blank setup on the right, a Conversational agent named "New Agent". Nothing is saved until you click Save.
• Build Agent with AI…, in the menu — describe the agent in a sentence and click CREATE AGENT. One call to the default model picks the name, type, system prompt, tools, repositories and databases, and the agent is saved straight away; review it before you rely on it. A generated name longer than 100 characters is cut to 100.

On SynapseOrch Cloud, New agent is the only way in, and a new agent is saved with Create.

---

Basic Info

Name — a clear, descriptive name, at most 100 characters. It is how the agent appears in the agent list, in Chat, in workflow step pickers and in the API.

Description — a short sentence describing what this agent does, shown in the agent list. A Team agent's lead reads its members' descriptions when it hands out work.

Agent Type — Conversational, Orchestrator, Code or Team. Code is offered while the coding_agent_enabled setting is on, which it is by default. An Orchestrator agent is created by Deploy as Agent on a workflow and is read-only here. See Agent Types.

Model — Use default (…) follows the default model set in Settings → Models. Pick a specific model to override it for this agent only — a cheaper, faster model for lightweight routing agents, a more capable one for research.

Reasoning — Default · …, Off, Low, Medium or High (on Cloud the first reads Workspace default · …). Default sets nothing and follows the workspace, naming the level it runs at. Shown only when the selected model can reason; higher costs more and takes longer. The editor says what Off does for the chosen model: a model that cannot stop thinking offers no Off (This model has no Off: the least it thinks is Low.), and one where off means its lowest level says so. See Thinking and Reasoning Effort.

Max Turns (Turn limit on Cloud) — how many reasoning turns the agent may take per request. Default 30 (50 for Code agents), up to 200. A workflow step's own Max turns overrides it.

Max Response Length — the most one model reply may be, in tokens. Blank follows the workspace's Max response length in Settings → Models. See Thinking and Reasoning Effort.

The screens, step by step: Agents and skills, in the Guides.

---

Capabilities (Tools)

Tools shows the available tools as cards, one per group, each with a badge:

• DEFAULT — tools every agent of this type gets. These cards are locked, and read "Included by default for … agents".
• MCP — tools from an MCP server.
• CUSTOM — your own custom tools.

Click a card's checkbox to enable or disable the whole group. Cards with several tools show how many are enabled (for example 2/5) and expand when clicked, so you can enable tools one at a time.

Self-hosted, there is no "all tools" switch in the form. On Cloud, Tools starts with Every tool (every tool except SQL) or Choose specific tools, which shows the cards. Give each agent the tools it needs; a customer support agent might only need the vault tools, while a data agent needs SQL and file tools.

---

Tool Policy, Skills, Planning and Memory

Tool Policy — whether calls that are destructive, reach the open world, or don't declare what they do are allowed, need a person's confirmation, or are denied. See Tool Policy.

Skills — pick skills from the Skills screen. Each costs one line in the prompt; the agent loads a skill's full instructions only when it needs them. See Skills.

Knowledge bases — shown while Knowledge is on. Tick up to 10 bases: the agent searches them with search_knowledge and cites the passages it uses. See Agents, chat and workflows.

Planning — on by default. The agent can keep a task list with update_tasks, shown live in the run log. Turn it off for one-shot agents. See Task Checklist.

Memory — off by default. The agent can save facts with remember, search past sessions with search_memory, and carries its memory index in its prompt. See Agent Memory.

---

System Prompt

The system prompt defines the agent's personality, instructions, and constraints. It is edited in Instructions; type directly, or use the AI Prompt Writer above it (self-hosted).

AI Prompt Writer

Describe what you want the agent to do in plain English and click GENERATE. SynapseOrch sends your description, the agent type, the tools currently enabled and the existing prompt to the default model, and replaces the system prompt with the result. For a Team agent it also sends the other agents' names and descriptions. With knowledge bases ticked, it sends their names and descriptions too, and the prompt tells the agent to answer from them first, cite each passage by its label, and say so when they do not hold the answer. When the model cannot answer, the reason shows under the field — The model couldn't write the prompt: and the provider's words — with a link to Settings → Models.

For example: "A customer support agent that looks up order status in the database and drafts polite responses. Always escalate to a human when a refund is requested."

Vault references

Type @ in the system prompt to pick a vault file; it is inserted as @[path]. Each time the agent runs, the file's contents are placed into the prompt, so you can keep long context — company policies, reference data, API docs — in the vault and share it between agents. See Vault for size limits.

Type {{ for a variable: {{ global.key }} is filled in from Variables each time the agent runs.

Preview mode

Switch the editor from Write to Preview to see the rendered markdown.

---

Repos and Databases (Code agents)

For Code agents, two more sections appear.

Linked Repositories lists the repositories indexed in Settings → Repos. Click one to give this agent semantic code search over it. See Code Repositories.

Linked Databases lists the connections in Settings → DB configs. Click one to put that database's schema into the agent's system prompt.

---

Members (Team agents)

For a Team agent, Members lists the agents its lead may hand work to. Leave all unticked to allow any agent; tick some to restrict it to those. The list leaves out the Team agent itself and builder agents; another Team agent may be listed, but is skipped when the team runs, since a member never leads a team of its own.

How members work — As a team (in parallel, sharing a task list) or One at a time — and its numbers are on Team agents.

---

Messaging Channels

The editor has five tabs: Setup, Messaging Channels, Runs, Metrics and Used by. On Cloud the agent is one page, and its channels are under Where it works.

Messaging Channels lists the channels this agent answers on — Telegram, and when self-hosted Slack, Discord, Teams or WhatsApp — and whether each is running. A channel can front several agents and an agent can answer on several channels; assign them under Channels. See Messaging.

Runs lists this agent's recent runs, Metrics its calls, tokens and estimated cost, and Used by the workflows, schedules, Team agents and messaging channels that use it.

---

Saving

While there is something to save, a bar at the bottom shows Save (Create for a new agent on Cloud). Click it to save the agent; it appears in the list and is ready to chat. Changes are not saved automatically: leaving an agent with unsaved changes asks first (Discard unsaved changes?), and the bar's Discard (Cancel on Cloud) puts back what was saved.

---

Editing and deleting

• To edit an agent, select it in the list, change any field, then click Save.
• To delete an agent, hover its row in the list and click the trash icon, then confirm. This cannot be undone. An agent something still uses — a widget, a channel, a phone number, a schedule, a live workflow step or a Team agent — is not deleted, and the refusal names them: 'Front desk' was not deleted: the widget 'Support' and the channel 'Team Telegram' use it; the schedule 'Every morning' runs it. Point them at another agent, or delete them, first.
• To duplicate an agent, hover its row and click the copy icon (Duplicate agent) — a new agent with the same configuration, named Research Agent (Copy) for an agent called Research Agent (Research Agent (copy) on Cloud), that you can rename and change. A long name is shortened so the copy keeps (Copy) within 100 characters.

---

Best practices

Keep system prompts focused. One job per agent produces cleaner results than one agent trying to do everything. You can always chain agents together using workflows.

Use selective tool access for agents with a narrow purpose. A scheduling agent that only needs to read and write vault files should not have browser or code search enabled.

Set a lower Max Turns for simple agents. A classification or routing agent rarely needs more than 3–5 turns. Lowering the limit keeps costs predictable at scale.

Assign cheaper models to lightweight agents. Use a fast, low-cost model for triage and routing, and reserve your strongest model for the agents doing the heavy reasoning.

Use the AI Prompt Writer as a starting point, then refine the output manually. Generated prompts give you a solid structure — add your specific constraints and edge cases on top.