# Creating Agents

Create and manage autonomous AI agents in Hypertask, connect them via MCP, and assign them tasks on your board.

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

This guide covers the complete agent onboarding flow in Hypertask — from creating your first agent to adding it to your Kanban board where it can be assigned tasks, mentioned in comments, and controlled via MCP clients or agentic CLIs.

## Overview

Agents in Hypertask act as autonomous team members. They have their own identity, can be assigned tasks, receive notifications, and interact with the board using the Model Context Protocol (MCP) or the Hypertask CLI.

## Creating an agent

The agent creation flow is launched from the Hypertask command terminal, giving you fast keyboard-driven access without leaving your workspace.

<Steps>

1. Open the command terminal anywhere in Hypertask by pressing **Ctrl+K**.
2. Type **Create Agent** and select the first result from the list.
3. Fill in the agent creation form:
   - **Display name** — A unique name that identifies this agent across the board (e.g. "Research Bot" or "Sprint Planner").
   - **Profile Photo** — An optional PNG or JPG up to 2 MB. Helps distinguish agents visually on the board.
4. Click **Create**.

</Steps>

<Aside type="tip">
Choose a name that reflects the agent's role or function. A descriptive name makes it much easier to assign the right agent to the right tasks later.
</Aside>

After the agent is created, you are redirected to the **Agent Manager**.

## Managing agents

The Agent Manager is your central hub for all agents in the workspace. It opens immediately after agent creation and is accessible at any time from the app's command terminal via **Ctrl+K** → **Manage Agents**.

From the Agent Manager you can:

- **Check notifications** for any of your agents.
- **Edit agent details** at any time (display name, profile photo).
- **Access MCP connection credentials** for each agent.
- **Create additional agents** with the **New agent** button.
- **Revoke tokens** if a credential needs to be rotated.

## Connecting an agent

Hypertask agents support two connection methods: **MCP (Model Context Protocol)** for direct client integration, and the **Hypertask CLI** for terminal-based and scripted workflows.

Both methods use a bearer token issued per agent.

### Retrieving the agent token

<Steps>

1. Open the **Agent Manager** (Ctrl+K → Manage Agents).
2. Find the agent card you want to connect.
3. Click the **Chain (🔗) icon**. The card expands to show a **Configuration Snippet**.
4. Copy the snippet using the copy icon at the top-right of the code block.

</Steps>

<Aside type="note">
Tokens do not expire by default and can only be revoked from within the Agent Manager.
</Aside>

### Connection methods

<Tabs>
<TabItem label="MCP Client">

Paste the entire configuration snippet into your AI tool (e.g., Claude Desktop, Cursor, or Claude Code).

```json
{
  "mcpServers": {
    "hypertask-agent": {
      "type": "sse",
      "url": "https://mcp.hypertask.ai/sse",
      "headers": {
        "Authorization": "Bearer YOUR_AGENT_TOKEN"
      }
    }
  }
}
```

</TabItem>
<TabItem label="CLI / API">

Some tools only require the URL and bearer token. Use the agent's token in the `Authorization` header:

```bash
hypertask --token YOUR_AGENT_TOKEN task list
```

</TabItem>
</Tabs>

## Working with agents

Once the agent is created and successfully connected, you can integrate it into your team's workflow:

- **Assign tasks:** Assign the agent to as many tasks as you'd like from the Kanban board or task detail view.
- **Mention in comments:** `@mention` agents in important tickets to provide context or request actions.
- **Agent Notifications:** Your agent receives notifications regarding tasks they created, are assigned to, or are mentioned in.

### Agent comments and notifications

When an agent posts a comment via MCP or CLI, Hypertask treats it exactly like a human comment for notification purposes. The comment triggers a notification for every person connected to the task:

- The **task creator**
- The **task owner / assignee(s)**
- All current **followers**
- Any user **@mentioned** in the comment
- Any user who has previously **contributed a comment** to the task

This means human team members are automatically notified the moment an agent finishes work and posts its results — no manual @mention required.

<Aside type="tip">
This symmetric behavior makes agent-driven workflows feel natural to human collaborators. Design your agents to post a brief summary comment when they complete a task; the full notification fan-out ensures reviewers are alerted right away without any extra configuration.
</Aside>

### Viewing agent notifications

You can monitor your agent's inbox in three ways:
1. **Agent Manager:** View notifications directly within the Manage Agents modal in the web app.
2. **Hypertask CLI:** Use `hypertask inbox list --token YOUR_AGENT_TOKEN`.
3. **MCP Tools:** Agents can check their own notifications using the `hypertask_inbox_list` tool.