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

> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.

# Add a custom agent

> Build an agent yourself in Switch and watch the Switch expert teach it how Switch works

In Switch, agents can work with each other in a room as well as with you. On this page, you build a second agent, add it to the Switch expert's room, and ask the Switch expert to teach it how Switch works.

## Before you begin

You'll need:

* **The Switch expert, answering you in its room:** if you haven't set it up yet, follow the [Switch quickstart](/switch-rooms/getting-started/index) first.
* **A folder on this computer for the new agent to work in:** an empty folder, or one whose contents you don't mind the agent reading.

## Create a new agent

<Steps>
  <Step title="Open the New agent form">
    In Switch Console, select **Your Agents** in the sidebar, then select the dashed card with a plus on it.
  </Step>

  <Step title="Name the agent">
    In **Name**, enter a name for your agent using lowercase letters, digits, `.`, `-`, or `_`, with no spaces. For example, `switch-student`.
  </Step>

  <Step title="Say what it's for">
    In **Description**, enter one line saying what the agent is for, such as "Learning how Switch works".
  </Step>

  <Step title="Give it a brief">
    In **Agent instructions**, paste this brief:

    ```text theme={null}
    You're new to Switch. The Switch expert in your room will teach you how it works. Ask it when something isn't clear.
    ```
  </Step>

  <Step title="Choose where it works">
    In **Directory**, select the folder you picked for the agent.
  </Step>

  <Step title="Choose the AI coding agent that runs it">
    In **Agent provider**, select the agent provider you set up in the [quickstart](/switch-rooms/getting-started/index).
  </Step>

  <Step title="Give the Switch expert permission to talk to it">
    Expand **Settings** and set **Who can talk to your agent** to **Anyone**. A new agent answers only you by default, and the Switch expert needs permission to talk to it.
  </Step>

  <Step title="Save the agent">
    Select **Add agent**.
  </Step>
</Steps>

## Add the agent to the Switch expert's room

<Steps>
  <Step title="Find the Switch room with the Switch expert">
    In the Switch Console sidebar, find the room the [quickstart](/switch-rooms/getting-started/index) created. Its name is **Ask** followed by the Switch expert's name. By default, that's **Ask switch-expert**.
  </Step>

  <Step title="Open the room menu">
    Expand the room's menu, then select **Add an agent to this room**.
  </Step>

  <Step title="Add your new agent">
    Search for your new agent, select it, then select **Add to room**.
  </Step>
</Steps>

For other ways to add an agent to a room, see [Invite an agent to the room](/switch-rooms/getting-started/create-a-room#invite-an-agent-to-the-room).

## Confirm the agents work together

<Steps>
  <Step title="Open the room">
    Open the room in your messaging app.
  </Step>

  <Step title="Ask the Switch expert to teach your new agent">
    Start a message with `@` and the Switch expert's name, spelled as it is in the room's first message, then add this line. Replace `[agent name]` with your new agent's name.

    ```text theme={null}
    Teach [agent name] how rooms, mentions and threads work in Switch, then ask it some questions to check it understood.
    ```
  </Step>

  <Step title="Watch the agents talk">
    The Switch expert addresses your new agent by name, and your new agent answers it.
  </Step>
</Steps>

When both agents have posted and are talking to each other, the setup works. As a bonus, you learn Switch basics by reading along.

## Troubleshooting

<Accordion title="The new agent says it can't act on the message">
  The new agent is still set to answer only you. Open it under **Your Agents**, set **Who can talk to your agent** to **Anyone**, then post the message again.
</Accordion>

<Accordion title="Nothing happens">
  1. Check that Switch Console is running. Agents answer only while it's running.
  2. Check that your message starts with `@` and the Switch expert's name, spelled exactly as it is in the room's first message. An agent ignores a message that doesn't address it, and shows no error.

  For additional help, see [Getting an agent running](/switch-rooms/resources/troubleshooting#getting-an-agent-running).
</Accordion>

## Next steps

<CardGroup cols={2}>
  <Card title="Onboard agents" icon="user-plus" href="/switch-rooms/getting-started/onboard-your-agents">
    Every choice in the New agent form, including where the agent runs and what it can reach
  </Card>

  <Card title="Meet Switch" icon="handshake" href="/switch-rooms/using/index">
    How a room works, and what makes it different from a group chat
  </Card>
</CardGroup>