non-linear-docs/05-agents-integration.md

# Non-Linear: AI Agent Integration

## Overview

Non-Linear treats AI agents as first-class actors — not assistants bolted onto a human interface, but independent participants with their own accounts, roles, permissions, and graph navigation capabilities.

## Two Agent Modes

### Agent as User

The agent operates independently within the project graph. It has its own account, picks up tasks, reports status, and navigates the decomposition tree autonomously.

**Primary use case:** One-person team (or small team) where an AI agent acts as a focused collaborator.

**How the graph helps:** The decomposition tree gives the agent *rails*. Instead of wandering through a flat list, the agent traverses a topology:

- "What's the highest-priority unblocked leaf node in Backend?" → graph traversal query
- "What's the status of the Auth component?" → read the subtree, aggregate child statuses
- "What should I work on next?" → find unblocked, assigned, in-progress leaves

**v0.1 capabilities:**
- Read any node (subject to policy)
- Post comments (status updates, analysis, questions)
- Change status on assigned nodes
- Traverse the tree (get parent, get children, get subtree)
- Query lateral links (what blocks this? what does this relate to?)

**Deferred (v0.2+):**
- Create child nodes (task decomposition)
- Propose reparenting
- Create lateral links
- Autonomous task pickup (self-assign from backlog)

### Agent as Assistant

The agent helps human users by analyzing the graph and suggesting actions. It doesn't act autonomously — it provides recommendations that humans execute.

**Primary use case:** Teams where AI augments human decision-making.

**Examples:**
- "Break this component into tasks" → agent suggests a set of child nodes, human approves
- "What's blocking the Auth epic?" → agent traverses the subtree and lateral links, reports findings
- "Summarize progress on Dashboard this week" → agent reads subtree statuses and recent comments
- "Are there any orphaned tasks?" → agent finds leaf nodes with no clear connection to higher-level goals
- "Suggest priority order for these tasks" → agent considers dependencies, blockers, and relationships

## Agent API (v0.1)

The agent API is a subset of the main API, governed by the same policy engine. Agents authenticate with API tokens tied to their actor account.

### Endpoints

#### Graph Traversal

```
GET /api/v1/nodes/{id}                    # Read single node
GET /api/v1/nodes/{id}/children           # Direct children
GET /api/v1/nodes/{id}/subtree            # Full subtree (depth-limited)
GET /api/v1/nodes/{id}/parent             # Parent node
GET /api/v1/nodes/{id}/links              # Lateral links (blocks, relates-to)
GET /api/v1/nodes/{id}/path               # Path from root to this node
GET /api/v1/projects/{id}/root            # Project root node
```

#### Queries

```
GET /api/v1/projects/{id}/nodes?status=in_progress&assignee=agent-123
GET /api/v1/projects/{id}/nodes?label=bug&status=backlog
GET /api/v1/projects/{id}/nodes?unblocked=true&status=todo
```

#### Actions (Write)

```
POST   /api/v1/nodes/{id}/comments        # Add comment
PATCH  /api/v1/nodes/{id}/status          # Change status
```

#### Deferred Actions (v0.2+)

```
POST   /api/v1/nodes/{id}/children        # Create child node
PATCH  /api/v1/nodes/{id}/parent          # Reparent
POST   /api/v1/nodes/{id}/links           # Create lateral link
DELETE /api/v1/nodes/{id}/links/{link_id} # Remove lateral link
PATCH  /api/v1/nodes/{id}                 # Edit node details
```

### Authentication

- Agents authenticate via API tokens (bearer tokens)
- Each token is tied to an actor (agent account)
- The actor has roles/policies assigned via the policy engine
- Token scoping: a token can optionally be restricted to a subset of the agent's permissions (defense in depth)

### Response Format

All responses include the agent's effective permissions on the returned resource:

```json
{
  "node": {
    "id": "uuid-123",
    "title": "Login component",
    "status": "in_progress",
    "labels": ["frontend", "p1"],
    "parent_id": "uuid-456",
    "children_count": 3,
    "links": [
      {
        "type": "blocked_by",
        "target_id": "uuid-789",
        "target_accessible": true,
        "target_title": "SSO integration"
      },
      {
        "type": "relates_to",
        "target_id": "uuid-000",
        "target_accessible": false,
        "target_title": null
      }
    ]
  },
  "permissions": {
    "can_edit": false,
    "can_change_status": true,
    "can_comment": true,
    "can_create_child": false
  }
}
```

Note: When a lateral link target is outside the agent's permission scope, `target_accessible` is `false` and details are withheld. The agent knows a link exists (and its type) but can't read the target.

## Agent Design Patterns

### Focused Worker Agent

An agent assigned to a specific subtree that processes tasks sequentially.

```
Loop:
  1. Query subtree for unblocked, assigned, todo items
  2. Pick highest priority
  3. Change status to in_progress
  4. Do work (external to tracker)
  5. Post comment with results
  6. Change status to done or in_review
  7. Repeat
```

### Triage Agent

An agent that scans the full project and suggests prioritization.

```
Loop:
  1. Query all nodes with status = backlog
  2. For each, check lateral links (blockers, dependencies)
  3. Post comment with suggested priority and rationale
  4. Optionally: change status from backlog to todo for approved items
```

### Decomposition Agent (v0.2+)

An agent that breaks high-level components into tasks.

```
Triggered when: a node has label "needs-decomposition"
  1. Read the node's title, description, and context (parent, siblings)
  2. Propose a set of child nodes (via comment or API)
  3. Human reviews and approves
  4. Agent creates the children
  5. Remove "needs-decomposition" label
```

## Integration Points

### Webhooks (v0.1)

The tracker emits webhook events for:

- `node.status_changed`
- `node.comment_added`
- `node.created`
- `node.link_created`

Agents can subscribe to webhooks to react to changes in real-time.

### MCP (Model Context Protocol) Compatibility (v0.2+)

Expose the Non-Linear API as an MCP server so AI agents built on LLM frameworks can connect natively without custom integration code.