Creating Agents

What is an agent in SquadOS?

An agent combines instructions, an AI model, tools, knowledge, entry points, and security rules. This configuration determines what it can answer or execute in a conversation.

Creating the record is only the beginning. A new agent still needs a clear prompt, the right access, and tests before it serves customers.

Before you create one

Define, in plain language:

• which problem the agent solves;
• who will talk to it;
• which information it may consult;
• which actions it may execute;
• when it should refuse, ask for help, or transfer the conversation.

You need the agents.write permission (edit agents). The creation button may also be unavailable when the plan has reached its active-agent limit, there is no default model, or your role has no valid category available. The counter on the page includes active agents only.

Create one manually

Open Agents in the panel menu and follow these steps:

1. Select New Agent.
2. Fill in Agent name. Use a name that identifies its function, such as Support Assistant or Sales SDR.
3. Under Initial category, select a category or Uncategorized. Roles with a restricted scope may be required to select an allowed category.
4. Select Create Agent.

SquadOS uses the organization’s default model and creates the agent with an empty prompt, active status, and its Hub entry enabled. No WhatsApp, Telegram, Instagram, widget, public page, or API is connected at this point.

On larger screens, the editor opens with AgentMaker displayed to help with the initial configuration. On mobile screens, the editor opens without that automatic panel. You can open or close AgentMaker from the button at the top of the editor.

The agent starts active

Because the new agent is already active and may become available in the Hub, do not treat it as ready. If the organization does not want to expose an incomplete configuration, open Advanced and deactivate the agent while you prepare and test it.

If creation reports an error, return to the list and search for the name before retrying. The agent and its entry points are currently saved in separate steps; a failure in the second step may leave the agent created despite the error message.

Other ways to start

• The Agent Gallery imports a published template into the organization. Review its prompt, model, tools, and category after importing; it also creates the agent active with its Hub entry enabled.
• Import Skill is a superadministrator-only preview. It turns a SKILL.md file into an inactive agent for review and does not automatically install tools described by the file. See Tools and Skills.

Identity and portrait

The agent receives a robot generated from a seed. To customize it, open Prompt and select the portrait next to the name.

The builder provides six groups: Eyes, Top, Chest, Body, Accent, and Glow. Top and Chest also accept None.

• Shuffle creates another complete combination.
• Back to random removes the fixed choices.
• Apply uses the combination in the form; Cancel closes without applying it.

The current editor does not offer a custom-image upload for a regular agent’s portrait.

The eight editor sections

Each sidebar item opens an independent area:

• Prompt — the agent’s name, description, and instructions. Specify its role, goal, context, boundaries, tone, and transfer criteria.
• Tools — actions the agent may execute. Enable only what it needs and verify the required permissions and accounts. See Native tools.
• Knowledge — vector bases, context blocks, and AutoLearn. Knowledge is connected in this section; it is not a tool added through the selector. See Knowledge Bases.
• Inboxes — shows where conversations arrive from. Channel connection and maintenance happen on the panel’s Inboxes page. See Inboxes.
• Model — defines the AI model, reasoning when supported, and model-related parameters.
• Multimodal — controls how incoming images, files, and audio are processed.
• Security — configures the guardrail against jailbreaks and prompt injection. See Guardrails.
• Advanced — combines active status, category, history, response size, tool use, temperature, message splitting, and archive or delete actions. See Advanced Settings.

Each section keeps its own changes. Use Save in the current section before leaving the page. If you try to leave with pending content, the editor lets you Discard and continue or Keep editing. Testing always uses the saved version, not the visible draft.

Recommended minimum configuration

Before the first test:

1. Under Prompt, write self-contained instructions and save them.
2. Under Knowledge, connect only the sources the agent needs.
3. Under Tools, enable only actions the agent should actually execute.
4. Under Model, confirm the model and expected cost.
5. Under Security and Advanced, review the guardrail, history, limits, and status.
6. Under Inboxes, confirm that no external entry point was connected before validation.

Test the saved version

Select Test Agent at the top of the editor. The button is unavailable while the agent is inactive.

The test opens a panel inside the editor itself. On the first message, SquadOS creates a persistent direct conversation with the agent; it can also be found in the Hub. From the panel menu, you can resume one of this agent’s 20 most recent test conversations or start another one.

If there are unsaved changes, the panel warns that it is using the previous version. Select Save and test to save the current section before chatting.

Test at least:

• one complete primary request;
• one request without enough information;
• one out-of-scope question;
• one action from each enabled tool, without using destructive data;
• one answer that depends exclusively on the connected knowledge base;
• an image, file, or audio message when the agent accepts those formats;
• refusal, transfer, and security boundaries.

Connect channels

After reviewing the results, open Inboxes in the panel menu and connect the desired channel to the agent. Each inbox has its own lifecycle, credentials, and state; creating the agent does not automatically publish WhatsApp, Telegram, Instagram, a widget, a public page, or an API.

Use the Triggers overview to choose a type, then follow the guide for the corresponding inbox.

Checklist before serving customers

• The prompt was saved and tested with realistic and out-of-scope cases.
• Knowledge bases and tools follow least privilege.
• The model, limits, and expected cost were reviewed.
• The guardrail and transfer behavior were validated.
• The agent is active only when it should receive conversations.
• Every connected inbox points to the correct agent.
• The team knows where to monitor Conversations.