non-linear-docs/05-AGENT-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 where an AI agent acts as a focused collaborator.

How the graph helps: The decomposition tree gives the agent rails:

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

Agent as Assistant

The agent helps human users by analyzing the graph and suggesting actions.

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

Examples:

• "Break this component into tasks" → agent suggests child nodes, human approves
• "What's blocking the Auth epic?" → agent traverses subtree and lateral links
• "Summarize progress on Dashboard this week" → agent reads subtree statuses and recent comments
• "Suggest priority order for these tasks" → agent considers dependencies and blockers

Agent API (v0.1)

Governed by the same policy engine as human users. Agents authenticate with API tokens tied to their actor account.

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              # Outbound lateral links
GET /api/v1/nodes/{id}/backlinks          # Inbound lateral links
GET /api/v1/nodes/{id}/path              # Path from root to this node
GET /api/v1/nodes/{id}/history            # Change history timeline
GET /api/v1/projects/{id}/root            # Project root node
GET /api/v1/projects/{id}/inbox           # Triage inbox (rootless nodes)

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
GET /api/v1/projects/{id}/nodes?cycle=current

Write Actions (v0.1)

POST   /api/v1/nodes/{id}/comments        # Add comment
PATCH  /api/v1/nodes/{id}/status          # Change status
PATCH  /api/v1/nodes/{id}/parent          # Triage: assign parent to inbox item

Deferred Actions (v0.2+)

POST   /api/v1/nodes/{id}/children        # Create child node
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

Response Format

All responses include effective permissions on the returned resource:

{
  "node": {
    "id": "uuid-123",
    "short_id": "NL-42",
    "title": "Login component",
    "status": "in_progress",
    "labels": ["frontend", "p1"],
    "parent_id": "uuid-456",
    "children_count": 3,
    "backlinks": {
      "blocked_by_count": 1,
      "relates_to_count": 2
    },
    "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
  }
}

Agent Design Patterns

Focused Worker Agent

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

Triage Agent

Loop:
  1. Query inbox for unplaced nodes
  2. For each, analyze title/description and match to existing subtrees
  3. Assign parent (place in tree)
  4. Post comment with rationale

Decomposition Agent (v0.2+)

Triggered when: a node has label "needs-decomposition"
  1. Read node context (parent, siblings, description)
  2. Propose child nodes via comment or plan-then-apply
  3. Human reviews and approves
  4. Agent creates children

Webhooks (v0.1)

Events emitted:

• node.status_changed
• node.comment_added
• node.created
• node.link_created
• node.reparented
• node.cycle_added

MCP Compatibility (v0.2+)

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