LSAP (Language Server Agent Protocol) is an open protocol that defines how AI coding agents interact with Language Servers. It transforms low-level LSP capabilities into high-level, Agent-Native cognitive tools, empowering Coding Agents with Repository-Scale Intelligence.
As an Orchestration Layer, LSAP composes atomic LSP operations into semantic interfaces. This aligns with Agent cognitive logic, allowing them to focus on high-level "intent realization" rather than tedious "editor operations."
The core difference of LSAP lies in how it defines "capabilities." LSP is designed for editors, providing Atomic operations; whereas LSAP is designed for Agents, providing Cognitive capabilities.
- LSP (Editor Perspective - Atomic):
- Editors require very low-level instructions:
textDocument/definition(jump),textDocument/hover(hover),textDocument/documentSymbol(outline). - The Agent's Dilemma: If an Agent uses LSP directly, it needs to execute a dozen interactions sequentially like a script (open file -> calculate offset -> request definition -> parse URI -> read file -> extract snippet) just to get a useful context.
- Editors require very low-level instructions:
- LSAP (Agent Perspective - Cognitive):
- LSAP encapsulates the complex chain of atomic operations above into a single semantic instruction.
- Example: A single request to "Find all references" triggers background execution of symbol localization, reference search, and context extraction, returning a consolidated Markdown Report.
sequenceDiagram
participant Agent as 🤖 Agent
participant LSAP as 🧠 LSAP Layer
participant LSP as 🔧 Language Server
Note left of Agent: Goal: Find all references of "User"
Agent->>LSAP: 1. Semantic Request (Locate + References)
rect rgb(245, 245, 245)
Note right of LSAP: ⚡️ Auto Orchestration
LSAP->>LSAP: Parse Semantic Anchor (Fuzzy Match)
LSAP->>LSP: textDocument/hover (Confirm Symbol Info)
LSAP->>LSP: textDocument/references (Get Reference List)
LSP-->>LSAP: Return List<Location>
loop For each reference point
LSAP->>LSP: textDocument/documentSymbol (Identify Function/Class)
LSAP->>LSAP: Read Surrounding Code (Context Lines)
end
end
LSAP-->>Agent: 2. Structured Markdown (Callers + Code Context)
LSAP is a formally defined protocol with complete JSON Schema specifications for all interaction models. The schema/ directory contains:
- Request/Response Schemas: Each capability (e.g.,
definition,outline,rename, etc.) has dedicated request and response schemas. - Field Definitions: Precise specifications of input parameters, output fields, and data types.
- Rendering Templates: Standardized Markdown templates for formatting responses, ensuring consistent agent-facing outputs.
This formal specification ensures:
- Type Safety: Strong contracts between agents and LSAP implementations.
- Interoperability: Different LSAP implementations can be swapped without breaking agent workflows.
- Extensibility: New capabilities can be added following the established schema patterns.
Example schema files: definition.request.json, definition.response.json, reference.request.json, reference.response.json, etc.
LSAP's interaction design strictly follows the Markdown-First principle: input expresses intent, and output provides refined knowledge.
Request (using symbol path):
{
"locate": {
"file_path": "src/models.py",
"locate": "User.validate"
},
"mode": "references",
"max_items": 2
}Alternative: Request (using find pattern):
{
"locate": {
"file_path": "src/models.py",
"find": "def validate<|>("
},
"mode": "references",
"max_items": 2
}Response:
# References Found
Total references: 12 | Showing: 2
### src/auth/login.py:45
In `LoginHandler.authenticate` (`method`)
```python
44 | def authenticate(credentials):
45 | if not User.validate(credentials):
46 | raise AuthError()
```
### src/api/register.py:28
In `register_user` (`function`)
```python
27 | def register_user(new_user_data):
28 | User.validate(new_user_data)
29 | db.save(new_user_data)
```Request:
{
"file_path": "src/models.py",
"mode": "outline"
}Response:
# Outline for `src/models.py`
## User (`class`)
### User.validate (`method`)
```python
def validate(data: dict) -> bool
```
---
Validate user data before saving.
### User.save (`method`)
```python
async def save(self) -> None
```
## Post (`class`)
### Post.publish (`method`)
```python
async def publish(self) -> PublishResult
```Request (Preview):
{
"locate": {
"file_path": "src/models.py",
"locate": "User.validate"
},
"new_name": "validate_data",
"mode": "rename_preview"
}Response:
# Rename Preview: `validate` → `validate_data`
ID: `abc123`
Summary: Affects 3 files and 8 occurrences.
## `src/models.py`
Line 15:
```diff
- def validate(data: dict) -> bool:
+ def validate_data(data: dict) -> bool:
```
## `src/auth/login.py`
Line 45:
```diff
- if not User.validate(credentials):
+ if not User.validate_data(credentials):
```
---
> [!TIP]
> To apply this rename, use `rename_execute` with `rename_id="abc123"`.Request (Execute):
{
"rename_id": "abc123",
"exclude_files": ["tests/**"],
"mode": "rename_execute"
}Response:
# Rename Applied: `validate` → `validate_data`
Summary: Modified 3 files with 8 occurrences.
- `src/models.py`: 1 occurrence
- `src/auth/login.py`: 4 occurrences
- `src/api/register.py`: 3 occurrences
---
> [!NOTE]
> Rename completed successfully. Excluded files: `tests/**`.
> [!IMPORTANT]
> You must manually rename the symbol in the excluded files to maintain consistency.While LSP provides atomic operations, LSAP offers composed capabilities that brings more powerful functionalities.
For instance, the Relation API (still in draft, but soon will be released) finds call paths between functions in a single request (handling traversal, cycles, and formatting), a task requiring complex orchestration in raw LSP.
LSAP centralizes these patterns, preventing agents from wasting tokens on orchestration and enabling advanced capabilities like architectural and impact analysis.
LSAP centralizes complexity. Instead of every Agent reimplementing LSP orchestration logic, LSAP provides a shared, optimized layer for these common patterns.
docs/: Core protocol definitions and Schema documentation.python/: Python SDK reference implementation.typescript/: TypeScript type definitions and utility library.web/: Protocol documentation site.
Claude Code have native LSP supports now - Well they don't.
serena is a powerful coding agent toolkit providing semantic retrieval and editing capabilities.
We welcome contributions! Please see our Contributing Guide for details on development workflows and design principles.