Creating a Subagent

This guide walks you through creating a new subagent from scratch.

Before you begin

  • You need to be signed in to an Assist workspace.
  • If you plan to scope the agent to specific projects or tools, those should already exist in the workspace.
  • If you want the agent to use a non-default model, a workspace admin needs to have made that model available.

Steps

1. Open the subagents page

From the main navigation, go to Subagents. You will see any existing agents in the workspace and, at the top, a section called Agent Favorites if you have starred any.

2. Click New Agent

The New Agent button is in the top-right of the subagents page. This opens the creation form.

3. Give the agent a label and description

  • Label — the name people will see when they pick this agent from a list or delegate to it. Keep it short and specific: "Support Digest", "WMS Drift Monitor", "Weekly AR Reminder". Required.
  • Description — one or two sentences about what the agent does. This is what the main chat reads when it is deciding whether to delegate to this agent, so write it for the delegator, not for a human reader. Optional but strongly recommended.

4. Write the Job Description

The Job Description is the agent's system prompt — the single most important field. It defines what the agent does, how it thinks about its work, and what it must not do. Required.

Good job descriptions:

  • State the agent's role in one sentence ("You are a support digest agent for the operations team.").
  • List the specific tasks it is expected to handle.
  • Name any guardrails ("You are read-only. Never call any write tool on the ERP.").
  • Describe the output format if it matters ("Always reply with a markdown summary followed by a bulleted action list.").

You can edit the job description later. It is common to iterate on it over the first few real runs.

5. Choose a model

Pick the LLM model the agent will run on from the Model dropdown. If you leave it empty, the agent uses the workspace default.

Match the model to the work:

  • Reasoning-heavy agents (analysis, planning, multi-step tool use) benefit from larger models.
  • High-volume, simple classification agents (triage, tagging) work well on faster, smaller models.

6. Scope the agent to projects (optional)

Use the Projects dropdown to select which LLM projects this agent can see. When you set this:

  • The agent can only call project-specific plan tools for the projects you select.
  • Other projects in the workspace are invisible to it.

Leave Projects empty if the agent should not be scoped to any project.

7. Pick the tools it can use

Use the Tools selector to pick which tools the agent has access to. Tools are grouped by tool pack — the built-in packs (web search, Slack, filesystem, knowledge base, timezone math, map lookups, etc.) and your organization's custom tools (in the dynamic_tools pack). Each pack header shows how many of its tools you have selected.

  • If you select no tools, the agent gets every tool in the workspace (subject to the project scope above). This is rarely the right choice for an agent that will see real data.
  • If you select any tools, the agent is restricted to only those tools — plus the built-in delegation and scheduling tools it always gets.

A few tips:

  • Start with the minimum set the agent actually needs. A tightly scoped agent is easier to trust, cheaper to run, and faster to debug.
  • Credentials and network permissions live on the tool, not on the agent. Selecting a tool gives the agent the exact access that tool was granted — no more, no less.
  • If a custom tool you expected to see isn't in the list, it's probably still a draft. Only tools that have been published (current version) appear here. See adding tools to a subagent for the full picture.
  • You can change the tool whitelist at any time from the edit page.

8. Link a knowledge base (optional)

If you have a Document Container (Knowledge Base) the agent should draw from, pick it here. The agent will search that container when it needs reference material.

9. Save

Click Save. You are taken back to the subagents list and your new agent appears there.

After it is created

On the edit page (open the pencil icon on the agent card) you can turn on additional capabilities that are not available at creation time:

  • Filesystem — give the agent a private text-file store. See Agent Filesystem.
  • Channel mappings — route Slack, Telegram, or Discord channels to the agent. See Routing channels to a subagent.
  • Custom instructions — add sandcastle-specific instructions when the agent is linked to a sandcastle.

Next steps