non-linear-docs/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:

{
  "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.