Building a custom agent

The catalog covers most asks. Building a custom agent is what you do once you've worked with the templated ones for a week and have a clear picture of the colleague you actually need — different domain knowledge, a tone the catalog doesn't carry, a workflow shaped around your team rather than a generic one.

This article walks the builder section by section. None of it is mandatory beyond a name; you can save early and refine over a few runs.

Two ways in

From the Agents page, click Create Agent. The dialog gives you two paths:

Build from scratch — opens a tiny dialog that asks for an agent name, then drops you into an empty builder.
Start with a template — opens the catalog inside the dialog; picking a template opens the builder pre-filled with that template's settings.

Most builds should start with a template — see The agent catalog. From-scratch is the right path when the job genuinely doesn't match anything in the catalog.

The builder layout

The builder is two panels:

Left — Agent Builder Chat. A conversational helper that can draft instructions for you, suggest tools, propose skills, or refine what you've already written.
Right — agent settings. The form you'll fill out. The top of the form is the agent's identity (always visible); below it sit five collapsible sections: Triggers, Instructions, Tools & Access, Skills, and Advanced.

The two panels work together — anything the chat suggests writes into the form, and you can edit it directly there too.

Identity

The fields at the top of the form. Most builds start here.

Avatar. Pick an icon or emoji. It's how the agent shows up on your roster.
Colour. A hue picker that tints the agent's accent colour. Cosmetic — useful if you want a visual cue across a team.
Name. Required (1–100 characters). Often a persona; sometimes a literal role name.
Description. Optional (up to 500 characters). The pitch teammates see on the agent card.
Job Title. Optional (up to 100 characters). The label that appears under the name everywhere the agent is referenced.
Business Area. One of nine values: Marketing, Legal, Strategy, Accounting, Sales, Engineering, HR, Operations, Custom. Used to group agents in your roster.

Instructions

The system prompt — the standing brief that shapes everything the agent produces. Up to 10,000 characters.

A few things that consistently improve outputs:

Open with one sentence describing what the agent's job is.
Spell out tone and format. If the agent writes for the brand, point at the brand voice doc as a skill.
List the things the agent should never do. Explicit constraints prevent drift more reliably than careful wording elsewhere.
Say where output should go. "Save final drafts to the Marketing → Drafts folder" prevents the agent from inventing a destination.

Iteration matters more than getting this right the first time. Most agents need two or three revisions in their first week — when outputs feel generic, the instructions are usually the lever to pull.

Tools & Access

A checkbox list grouped by category — Workspace (page and task tools, search, comments) and External (web search, URL extraction, plus every connected integration: Gmail, Slack, Jira, Drive, and the rest). Tools the agent isn't given simply aren't available when it runs; nothing fails silently.

The External block reflects what's connected at the moment you open the builder. Integrations connected in Settings → Integrations show up here as toggleable blocks — toggle one on to grant this agent the integration's full action set. See Giving an agent access to an integration for the full pattern.

Common picks for a writing or research agent:

Search the workspace, so the agent can find context.
Create and edit pages, so it can save what it produces.
Add comments, so it can post conclusions back to tasks.
Web search and URL extraction, when the work needs outside sources.

Inspect the live list in the form — what's available depends on which workspace tools, external tools, and integrations are wired at the moment you open the builder; don't assume from this article.

Skills

A skill is a knowledge base page the agent reads before answering. Use case: a brand voice doc tagged as a skill, with a custom prompt that tells the agent how to apply it ("rewrite every output to match this voice"). Skills are workspace-scoped — once a page is set up as a skill, every agent can opt in.

You toggle individual skills on or off for this agent, and each enabled skill can carry a per-skill custom prompt that overrides the default treatment.

Triggers (advanced — most users skip this)

The Triggers section supports five types — Schedule, Event, Webhook, Mention, and Condition. They cover unusual cases like a webhook-driven agent or one that fires on a workspace event.

Most users should leave this alone. The standard way to schedule an agent is to assign it to a task and use the AI Schedule fields there — see Scheduling an agent. The Triggers section is a power-user surface and exists for cases the task-level schedule can't cover.

Advanced

Two settings live here:

Default Project. When someone starts a new chat with this agent, this project is pre-selected. They can change it per conversation.
Response Length. Three presets — Short (~750 words), Medium (~3,000 words), Long (~6,000 words). Medium works for most agents.

The Agent Builder Chat

The left-hand chat is a build assistant, not the agent itself. It can:

Draft instructions from a short brief you describe in plain language.
Suggest tools given the work you've described.
Propose skills (with custom prompts) from pages you point it at.
Refine fields you've half-written.

Anything it produces writes into the form on the right; you can accept, edit, or overwrite. Treat it as a faster way to get a first draft, not as a verdict on what's right.

Saving and iterating

The only required field to save is Name. Everything else is optional — but a real agent usually needs at least instructions and one or two tools to be useful.

Save and the new agent lands in your roster, ready to chat or be assigned to a task. The expected loop is iterative: run it a few times, watch where it drifts, and tighten the instructions or trim the tool list. Most agents settle into shape over the first week.

Tips and gotchas

The label is Job Title, not Role. Member-level Role (owner, admin, member, viewer) is a separate field for human teammates and is fine to use.
The Tools & Access list is dynamic. Don't memorise it — re-check the live list when you build.
Builder Chat suggestions write into the form, but nothing saves until you hit save. If you close the builder mid-iteration, unsaved changes are lost.