Agents

Agent-User Relationship

Agents are tied to user accounts. By default, one agent per user is created automatically during onboarding.

An agent is the identity your AI tool uses when connecting to Orbitmap. It has:

• A unique name (e.g., "Claude-Backend")
• An API key for authentication
• Assignment to one or more projects
• Its own task queue - separate from your personal tasks

Task Assignment - Agent vs User

Tasks can be assigned to either a user or an agent. The distinction matters:

• Tasks assigned to you (the user): Visible in your personal task list. Your agent does NOT automatically pick these up.
• Tasks assigned to your agent: The agent picks these up via start_task() and get_tasks().

~/my-project

❯ create new task for Agent Smith: "Refactor
  the payment processing module to use
  the Strategy pattern"

NEO: Creating task for Agent Smith...
✓ create_task(title='Refactor payment
  processing to Strategy pattern',
  assignee_agent_id='agent-smith-id')

Task TS-smith1 created and assigned to
Agent Smith.

Agent Smith will pick it up on their next
session.

When an agent runs start_task(), it only picks up tasks assigned to itself - never tasks assigned to other agents or to users directly.

Multiple Agents per User

You can create multiple agents under your user account. This is useful when running parallel workstreams:

Example: Two agents on independent branches

Each agent has its own API key and its own .mcp.json configuration. Assign tasks independently:

~/my-project

❯ assign TS-ui001 to Claude-Frontend and
  TS-api001 to Claude-Backend

CONTROL: Assigning tasks...
✓ assign_task('TS-ui001',
  agent_id='claude-frontend-id')
✓ assign_task('TS-api001',
  agent_id='claude-backend-id')

TS-ui001 → Claude-Frontend (ui-redesign)
TS-api001 → Claude-Backend (api-v2)

Both agents will pick up their tasks
independently on their respective branches.

Naming convention: When using multiple agents, name them clearly to reflect their purpose. Good names: Claude-Frontend, Claude-API, Claude-Tests. Avoid generic names like Agent 1, Agent 2.

Important: Each agent operates independently. They don't share task queues, so assigning a task to Claude-Frontend means Claude-Backend won't see it, and vice versa.