---
title: "Create an Agent"
description: "The three ways to create a Chickpea Agent, what each one saves, and how to prove the new handle answers in Slack."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.chickpea.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an Agent

Creating an **Agent** saves one new teammate: a name, a handle, an avatar, and the instructions it follows everywhere it works. Where publishing gives an Agent that already exists reach into a channel, creating one brings the teammate into being with no channels, no connections, and no memory. This page covers the three doors that create an Agent, what each one saves, and how to prove the new handle answers in Slack.

## Prerequisites

- **A Chickpea membership.** Every role can create an Agent, including Member. Publishing that Agent to a Slack channel also requires that you belong to the channel in Slack.
- **A paid Slack plan and a workspace policy that lets Chickpea create user groups.** A handle is a Slack user group with zero members. Without both, the Agent is still saved and only the handle fails.
- **A name and handle that are not "chickpea".** That identity is reserved for the system Agent, and Chickpea refuses any spelling that normalizes to it.

## Create from Slack

Ask in the channel where the teammate should work. Chickpea creates one base Agent immediately, with no proposal and no second confirmation.

1. **Mention `@Chickpea` and describe the job.**

   > **`@Chickpea`** make me a support agent that answers billing questions and knows our refund policy

2. **Read the introduction it posts back.** The new Agent introduces itself in the thread under its own name, handle, and avatar, and repeats the description you gave it.
3. **Follow the `Connect X` links if you named a service.** Connectors you named in the message become up to three independently authorized `Connect X` actions in that welcome. The links never grant access on their own; a person completes each one in the browser.
4. **Open `View Agent`** to finish anything else in Admin.

Where you ask decides the reach. A request made in a channel grants that exact channel and nothing more. A request made in a DM creates no channel grant at all, so the Agent is unpublished until you publish it.

Two cases do not apply immediately. An Agent that any workspace member may edit is an authority change, so it comes back as a proposal to confirm first. A name or handle that matches an Agent you can already edit returns a clarification instead: use the existing Agent, or choose a distinct name and handle.

## Create in Admin

1. In **Admin → Agents**, choose **New Agent**. The address is `/admin/agents/new`.
2. Under **Details**, enter a **Name**. It is required and it is the name shown on the Agent's Slack replies. The optional **Description** is capped at 500 characters.
3. Under **Destinations → Slack**, check the **Handle**. It is derived from the name: lowercased, with every character outside `a-z`, `0-9`, `_`, and `-` replaced by `-`, and capped at 80 characters. Edit it here if you want something else.
4. On the **Instructions** tab, write what the Agent does. Saving without it fails with `Agent instructions are required.`
5. Use the other tabs now or later: **Skills**, **Connections**, **Repositories**, **Memory**, **Schedules**, and **Model**.
6. Choose **Create Agent**. Chickpea saves the Agent with a generated avatar and an unpublished handle.
7. Select **Choose first channel**, pick a channel, then select **Attach**. Channels are offered only after the Agent exists.

Publishing to a public channel joins the bot automatically. Private channels need someone to `/invite @Chickpea` first, and the grant stays pending until then.

## Create from a coding agent

The management MCP server creates an Agent in one call. Send exactly one `create_agent` operation in `apply_workspace_changes` and it applies immediately; `propose_workspace_changes` rejects Agent creation outright.

```json
{
  "idempotencyKey": "<your-key>",
  "operations": [
{
  "itemId": "agent",
  "kind": "create_agent",
  "clientRef": "research",
  "agent": {
    "id": "agent_research",
    "name": "Research",
    "description": "Synthesizes research for the team.",
    "requestedHandle": "research",
    "editPolicy": "creator_and_admins",
    "instructions": "Synthesize evidence and cite sources.",
    "enabled": true,
    "model": "<provider>/<model-id>",
    "skills": [],
    "mcpServers": [],
    "apiConnections": [],
    "repositories": []
  }
}
  ]
}
```

An MCP request derives no channel reach. Publishing is a separate `grant_agent_channel` operation that requires confirmation. One apply request accepts at most 25 ordered operations, and the acting membership is recorded as the creator from the authenticated session, never from a tool argument.

## Verify

Mention the new handle in a channel it was granted, in a new top-level message. A threaded reply under the Agent's own name and avatar is the proof; nothing earlier counts.

New configuration is active on the next newly admitted Slack event, including a reply in a thread that is already open. If nothing comes back, check that the Agent holds an active grant for that channel, and that your message actually mentioned the handle: a top-level message that mentions no one is dropped before any model is involved.

## Fix a blocked handle

The Agent is saved either way. Chickpea records the reason on the Agent's page in Admin and offers **Retry** next to the exact fix.

| What Slack returned | What it means | What to do |
|---|---|---|
| Policy denied | The workspace lets only Owners and Admins create user groups | Have a Slack Owner or Admin open **Roles & permissions → Account types** at `slack.com/admin`, choose **Edit permission** next to **Create and edit user groups**, add Members, save, then select **Retry** |
| Paid plan required | Slack user groups need a paid plan | Upgrade the Slack workspace, then select **Retry** |
| Handle already in use | Slack handles are workspace-global across members and user groups | Take one of the suggested handles, which append `-2`, `-3`, and so on, or enter another, then select **Retry** |
| Two-factor required | Slack will not manage the group until the acting member completes 2FA | Complete two-factor authentication in Slack, then select **Retry** |

Reconnecting Slack does not change a policy denial. It is the fix for one case only: Chickpea no longer holds a valid Slack authorization for the workspace, which shows as **Reconnect Slack** instead of **Retry**.

## What creation does not do

- **It grants nothing beyond the source channel.** No connection, repository, schedule, or extra channel rides inside the creation itself. Each is a separate change with its own policy.
- **It shares nothing with other Agents.** A connection authorized for one Agent belongs to that Agent; another Agent starts its own setup even for the same external account.
- **It starts with no memory.** An Agent has one durable memory of its own, with no channel or user scope, and creation writes nothing into it.

## Next steps

- [Agents](/agents): instructions, models, connections, skills, memory, and schedules for the Agent you created.
- [In Slack](/slack): handles, channel grants, and what else `@Chickpea` can do from a message.
- [Admin](/admin): who can sign in, what each role may do, and the management MCP behind the third door.
- [How Chickpea works](/start/how-it-works): what happens between a mention and a reply.

Source: https://docs.chickpea.co/agents/create-an-agent/index.mdx