From 557cf46df72994b2ccee53643c56c1b7554b98c5 Mon Sep 17 00:00:00 2001 From: oberon Date: Tue, 5 May 2026 00:50:51 +0300 Subject: [PATCH] Add agents-integration.md --- agents-integration.md | 193 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 agents-integration.md diff --git a/agents-integration.md b/agents-integration.md new file mode 100644 index 0000000..710751a --- /dev/null +++ b/agents-integration.md @@ -0,0 +1,193 @@ +# 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. \ No newline at end of file