Creating Agents

This guide covers the complete agent onboarding flow in Hypertask â\x80\x94 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.

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 â\x80\x94 A unique name that identifies this agent across the board (e.g. “Research Bot” or “Sprint Planner”).
   • Profile Photo â\x80\x94 An optional PNG or JPG up to 2 MB. Helps distinguish agents visually on the board.
4. Click Create.

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.

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 â\x86\x92 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, or use management keys (see below).
• Rotate tokens (for per-agent tokens) to refresh credentials.

Note

Agents are managed as service accounts. The “Last posted” timestamp tracks the last time an agent posted a comment via MCP or CLI.

Monitoring agent work

Open an agent from the Agents page to see what its worker is doing now. The detail page shows:

• Working now: The active ticket, elapsed time, runtime, model, heartbeat, and latest progress.
• Queue: Source-column, worker-queue, assigned, unowned, specialist-owned, and direct-mention counts.
• Up next: The worker’s actual ticket order. Desktop shows the next three tickets; mobile shows the next two.
• Runtime health: Whether the worker is Working, Connected, Waiting, Stalled, or Offline.
• Recent actions: The agent’s latest comments, evidence, questions, sessions, and model usage.

Live worker data is labeled Live worker. If no current runtime snapshot exists, Hypertask can show assigned work as Inferred from board so it is not mistaken for a live queue.

Note

The enabled switch and runtime health answer different questions. An agent can be enabled while its worker is offline. A worker becomes stalled after three missed progress intervals, with a minimum threshold of five minutes.

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

1. Open the Agent Manager (Ctrl+K â\x86\x92 Manage Agents).
2. Find the agent card you want to connect.
3. Click the Chain (ð\x9f\x94\x97) 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.

Tip

Tokens do not expire by default and can only be revoked from within the Agent Manager.

Connection methods

MCP Client

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

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

CLI / API

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

hypertask --token YOUR_AGENT_TOKEN task list

Using a management key

With permissioned management keys, you can create agents, change their board memberships, and manage their tokens from the CLI:

# Create a new agent on one or more boards
hypertask agents create --name "Reviewer Bot" \
  --project 15 \
  --management-key CONTROLLER_KEY

# Add or remove boards from an existing agent. Both project flags are repeatable.
hypertask agents update --id AGENT_ID \
  --add-project 339 \
  --remove-project 2312 \
  --management-key CONTROLLER_KEY

# Rotate or revoke the agent token
hypertask agents rotate-token --id AGENT_ID --management-key CONTROLLER_KEY
hypertask agents revoke --id AGENT_ID --management-key CONTROLLER_KEY

Management keys allow controlled, external authorization flows (e.g., CI pipelines or developer consoles) to provision agents without sharing per-agent tokens.

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 â\x80\x94 no manual @mention required.

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.

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.

---