Add agents-integration.md
This commit is contained in:
parent
aa5e1408cf
commit
557cf46df7
193
agents-integration.md
Normal file
193
agents-integration.md
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user