PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/z-archive/cursor-doc/doc_cursor_ai_agent_architecture.md

18 KiB
Raw Blame History

Cursor AI Agent Architecture - Agent & Planning Mode

Stand: Februar 2026 Zweck: Technische Dokumentation der AI-Agenten-Integration in Cursor (VS Code Fork) als Grundlage fuer die Entwicklung einer eigenstaendigen Chat-Komponente mit API-Zugang

1. Ueberblick

Cursor ist ein Fork von Visual Studio Code, erweitert um tiefgreifende AI-Faehigkeiten. Im Gegensatz zu VS Code Extensions, die durch die Extension-API limitiert sind, hat Cursor als echter Fork vollen Zugriff auf den Rendering-Pipeline, den AST-Level und die Language Server Infrastructure.

Die AI-Integration besteht aus zwei Hauptkomponenten:

  1. Client (Body): Die Electron/VS Code-basierte Desktop-Applikation mit Custom-UI-Elementen (Chat-Sidebar, Composer-Panel, Inline-Completions)
  2. Backend (Brain): Cloud-Services fuer LLM-Orchestrierung, Prompt-Konstruktion, Codebase-Indexierung und Embedding-Storage
User Interaction
  ↓
Cursor Client (Electron / VS Code Fork)
  ├─> Chat Panel UI (Custom Webview)
  ├─> Composer Panel (Multi-File Editor)
  ├─> Inline Completions (Tab)
  └─> Cmd/Ctrl+K (Inline Edit)
        ↓
  Context Assembly Layer
  ├─> Open Files / Cursor Position
  ├─> Semantic Search (RAG)
  ├─> AST / Language Server Data
  └─> Conversation History
        ↓
  Cursor Backend (Cloud)
  ├─> Prompt Construction
  ├─> Model Routing (GPT / Claude / Gemini / Custom)
  ├─> Tool Orchestration
  └─> Response Streaming
        ↓
  Response Processing (Client)
  ├─> Text Rendering (Markdown)
  ├─> Code Diff Application
  ├─> Tool Call Execution
  └─> Plan/Todo Management

2. Interaction Modes

Cursor bietet vier Modi, die ueber Ctrl+. gewechselt werden koennen:

2.1 Agent Mode (Standard-Ausfuehrungsmodus)

Zweck: Autonomes Implementieren, Refactoring, Bug-Fixing

Faehigkeiten:

  • Multi-File Exploration und Editing
  • Terminal-Kommando-Ausfuehrung (sandboxed)
  • Codebase-Suche (semantisch + grep)
  • Iterative Verfeinerung mit Compiler/Linter-Feedback
  • Parallele Tool-Aufrufe fuer Geschwindigkeit

Ablauf:

User Prompt
  ↓
Context Assembly
  ├─> user_info (OS, Shell, Workspace)
  ├─> project_layout (File Tree Snapshot)
  ├─> open_files / cursor_position
  └─> edit_history / linter_errors
        ↓
System Prompt Injection
  ├─> Role Definition ("AI coding assistant, pair programmer")
  ├─> Communication Guidelines (Markdown, Code Citations)
  ├─> Tool Calling Rules (15+ Tools)
  ├─> Context Strategy (Parallel Execution, Thorough Exploration)
  └─> Code Change Guidelines (Read before Edit, Fix Lints)
        ↓
LLM Request (POST /v1/chat/completions)
  ├─> model: "claude-4.6-opus" | "gpt-5.2" | ...
  ├─> temperature: 0
  ├─> messages: [system, user_context, user_query]
  ├─> tools: [15+ tool definitions]
  ├─> tool_choice: "auto"
  └─> stream: true
        ↓
Streaming Response
  ├─> Text Chunks (Markdown)
  ├─> Tool Calls (JSON)
  │     ├─> Tool Execution (Client-Side)
  │     └─> Tool Results → Next LLM Turn
  └─> Completion

2.2 Plan Mode (Planungsmodus)

Zweck: Komplexe Features zerlegen, Codebase analysieren, Implementierungsplaene erstellen

Aktivierung: Shift+Tab im Agent Input oder Ctrl+. → Plan

Kernmerkmal: Read-Only - es werden keine Aenderungen am Code vorgenommen

System Reminder bei Plan Mode:

Plan mode is active. The user indicated that they do not want you to execute
yet -- you MUST NOT make any edits, run any non-readonly tools (including
changing configs or making commits), or otherwise make any changes to the
system.

Plan-Mode-Workflow:

User beschreibt komplexe Aufgabe
  ↓
Codebase Research (Read-Only)
  ├─> Semantic Search nach relevanten Dateien
  ├─> File Reading fuer Kontextverstaendnis
  └─> Grep fuer spezifische Symbole
        ↓
Klaerende Fragen an User
  ├─> Anforderungen praezisieren
  ├─> Implementierungsvarianten abklaeren
  └─> Scope eingrenzen
        ↓
Plan-Erstellung (create_plan Tool)
  ├─> Markdown-Dokument mit Datei-Referenzen
  ├─> Code-Beispiele und Snippets
  ├─> Strukturierte Todos mit IDs und Abhaengigkeiten
  └─> Uebersicht (1-2 Saetze)
        ↓
User Review & Inline-Editing
  ├─> Plan direkt im Editor bearbeitbar
  ├─> Todos hinzufuegen/entfernen
  └─> Bei Zufriedenheit: Ausfuehrung starten

Plan-Datenmodell (create_plan Tool):

{
  "name": "Kurzer Plan-Name (3-4 Worte)",
  "overview": "1-2 Saetze Zusammenfassung",
  "plan": "# Plan Title\n\nMarkdown-Inhalt mit Dateireferenzen...",
  "todos": [
    {
      "id": "setup-auth",
      "content": "Auth-Middleware implementieren",
      "dependencies": []
    },
    {
      "id": "implement-ui",
      "content": "Login-Formular erstellen",
      "dependencies": ["setup-auth"]
    }
  ]
}

2.3 Ask Mode (Frage-Modus)

Zweck: Code verstehen, Fragen beantworten ohne Aenderungen Einschraenkung: Read-Only, keine Write-Tools verfuegbar

2.4 Debug Mode (Fehlerbehebungs-Modus)

Zweck: Systematische Fehleranalyse mit Hypothesen, Log-Instrumentierung, Runtime-Analyse

3. Communication Protocol

3.1 Transport Layer

Cursor kommuniziert mit dem Backend ueber ConnectRPC (gRPC-Web Variante) mit Protocol Buffers (Protobuf) als Serialisierungsformat.

Primaerer Endpoint: https://api2.cursor.sh

Encoding: HTTP/2 mit binaerer Protobuf-Kodierung im Envelope-Format:

[type:1 byte][length:4 bytes Big-Endian][payload:N bytes]

3.2 Protobuf-Schema (Reverse Engineered)

Service: aiserver.v1.ChatService

Kern-Messages:

message GetChatRequest {
  ModelDetails modelDetails = 1;
  repeated ConversationMessage conversation = 2;
}

message ModelDetails {
  optional string modelName = 1;
}

message ConversationMessage {
  string text = 1;
  MessageType type = 2;

  enum MessageType {
    MESSAGE_TYPE_HUMAN = 0;
    MESSAGE_TYPE_AI = 1;
  }
}

Streaming-Methode: StreamChat() bzw. StreamUnifiedChatWithTools()

  • Antworten kommen als iterativer Stream
  • Jeder Chunk enthaelt ein text-Feld mit partiellem Content

3.3 OpenAI-kompatibles Chat Completions API

Parallel zum Protobuf-Protokoll nutzt Cursor intern das OpenAI Chat Completions Format:

POST /v1/chat/completions

Request-Struktur:

{
  "model": "claude-4.6-opus",
  "temperature": 0,
  "user": "github|user_ID",
  "messages": [
    {
      "role": "system",
      "content": "[System Prompt mit allen Instruktionen]"
    },
    {
      "role": "user",
      "content": "<user_info>...</user_info>\n<project_layout>...</project_layout>"
    },
    {
      "role": "user",
      "content": "<user_query>...</user_query>\n<system_reminder>...</system_reminder>"
    }
  ],
  "tools": [ /* 15+ Tool-Definitionen */ ],
  "tool_choice": "auto",
  "stream": true
}

Kontext-Injection im User-Message:

Tag Inhalt
<user_info> OS, Datum, Shell, Workspace-Pfad
<project_layout> Dateibaum-Snapshot (einmalig zu Gespraechsbeginn)
<user_query> Der eigentliche User-Prompt
<system_reminder> Dynamische Modus-Instruktionen (z.B. Plan Mode aktiv)
<open_and_recently_viewed_files> Offene und kuerzlich angesehene Dateien

4. System Prompt Architektur

Der System Prompt ist das Herzstrueck der AI-Steuerung. Er wird vom Cursor-Backend zusammengebaut und besteht aus folgenden Bloecken:

4.1 Prompt-Bloecke

System Prompt Assembly
  ├─> Role Definition
  │     "You are an AI coding assistant, powered by [model]. You operate in Cursor."
  │     "You are pair programming with a USER to solve their coding task."
  │
  ├─> <communication>
  │     Markdown-Formatierung, Code-Citations, Math-Notation
  │
  ├─> <tool_calling>
  │     Regeln fuer Tool-Nutzung: Nicht Tool-Namen erwaehnen, Standard-Format nutzen
  │
  ├─> <maximize_parallel_tool_calls>
  │     Unabhaengige Tool-Calls parallel ausfuehren
  │
  ├─> <maximize_context_understanding>
  │     Gruendliche Exploration, Symbol-Tracing, Semantic Search Strategie
  │
  ├─> <making_code_changes>
  │     Read before Edit, Dependency Files, Linter-Fixes
  │
  ├─> <citing_code>
  │     CODE REFERENCES (startLine:endLine:filepath) vs MARKDOWN CODE BLOCKS
  │
  ├─> <task_management>
  │     todo_write Tool fuer komplexe Tasks
  │
  ├─> Workspace Rules (.cursor/rules/)
  │     Projekt-spezifische Coding-Konventionen
  │
  ├─> User Rules
  │     Benutzerdefinierte Praeferenzen
  │
  └─> MCP Instructions
        Konfigurierte MCP-Server und deren Nutzungshinweise

4.2 Mode-spezifische Anpassungen

Der System Prompt wird je nach aktivem Mode modifiziert:

Mode Zusatz-Instruktionen
Agent Volle Tool-Palette, Edit-Berechtigung, Terminal-Zugang
Plan Read-Only Reminder, create_plan Tool verfuegbar, keine Edits
Ask Read-Only, eingeschraenkte Tools, Erklaer-Fokus
Debug Hypothesen-getriebene Analyse, Log-Instrumentierung

5. Tool-System

Cursor stellt dem LLM 15+ spezialisierte Tools zur Verfuegung, definiert im OpenAI Function Calling Format.

5.1 Tool-Kategorien

Code-Verstaendnis:

  • codebase_search / SemanticSearch - Semantische Suche nach Bedeutung
  • grep / Grep - Exakte Text/Regex-Suche (basiert auf ripgrep)
  • read_file / Read - Dateien lesen mit optionalem Offset/Limit
  • glob_file_search / Glob - Dateien nach Muster finden
  • list_dir - Verzeichnisinhalt auflisten

Code-Aenderung:

  • edit_file - Intelligentes Code-Editing mit // ... existing code ... Markern
  • StrReplace - Exakte String-Ersetzungen
  • Write - Neue Dateien erstellen / ueberschreiben
  • delete_file / Delete - Dateien loeschen
  • edit_notebook / EditNotebook - Jupyter Notebook Zellen bearbeiten

Ausfuehrung:

  • run_terminal_cmd / Shell - Sandboxed Terminal-Kommandos
  • web_search / WebSearch - Web-Recherche
  • WebFetch - URL-Inhalte abrufen

Projekt-Management:

  • todo_write / TodoWrite - Task-Tracking mit Status
  • create_plan - Strukturierte Planungsdokumente

Linting:

  • read_lints / ReadLints - Linter-Fehler auslesen

Subagenten:

  • Task - Spezialisierte Sub-Agenten starten (generalPurpose, explore, browser-use)
  • SwitchMode - Modus wechseln

5.2 Tool-Definition Format

Jedes Tool wird als OpenAI Function Definition spezifiziert:

{
  "type": "function",
  "function": {
    "name": "codebase_search",
    "description": "semantic search that finds code by meaning...",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "A complete question about what you want to understand"
        },
        "target_directories": {
          "type": "array",
          "items": { "type": "string" }
        },
        "explanation": {
          "type": "string",
          "description": "Why this tool is being used"
        }
      },
      "required": ["query", "target_directories", "explanation"]
    }
  }
}

5.3 Tool-Aufruf und Antwort-Zyklus

LLM generiert Tool-Call
  ↓
{
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "read_file",
      "arguments": "{\"target_file\": \"src/main.py\"}"
    }
  }]
}
  ↓
Client fuehrt Tool aus (lokal)
  ↓
Tool-Result wird als neue Message eingefuegt
  ↓
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "1|import os\n2|import sys\n..."
}
  ↓
Naechster LLM-Turn mit Tool-Result im Kontext
  ↓
LLM generiert Text-Antwort oder weitere Tool-Calls

5.4 Parallele Tool-Ausfuehrung

Cursor optimiert auf parallele Tool-Calls. Wenn keine Abhaengigkeiten bestehen, werden mehrere Tools gleichzeitig aufgerufen:

Beispiel: "Fuege Authentication hinzu"
  ↓
Parallel:
  ├─> codebase_search("How does authentication work?")
  ├─> grep("auth|login|session")
  ├─> read_file("src/app.py")
  └─> web_search("best practices authentication 2026")
        ↓
Sequential (abhaengig von Ergebnissen):
  ├─> read_file("src/middleware/auth.py")  [gefunden durch search]
  └─> edit_file("src/routes/login.py")    [basierend auf Kontext]

6. Codebase-Indexierung und RAG

6.1 Indexierungs-Pipeline

Projekt oeffnen
  ↓
Background Scanning
  ├─> Dateien in Chunks aufteilen (tree-sitter fuer AST-basiertes Splitting)
  ├─> Chunks: ~einige hundert Tokens, an logischen Grenzen (Funktionen, Klassen)
  └─> .gitignore / .cursorignore respektieren
        ↓
Embedding-Berechnung
  ├─> OpenAI Embedding Model oder Custom Model
  └─> Vektor-Repraesentation des semantischen Inhalts
        ↓
Vektor-Datenbank (Backend)
  ├─> Embeddings mit Metadaten (Datei, Zeilen, Chunk-ID)
  └─> Nearest-Neighbor-Suche fuer Queries

6.2 Retrieval-Augmented Generation (RAG)

User-Query
  ↓
Query → Embedding-Vektor
  ↓
Nearest-Neighbor-Suche in Vektor-DB
  ↓
Top-K relevante Code-Chunks
  ├─> Dateiname + Zeilennummern
  └─> Code-Inhalt
        ↓
In LLM-Prompt eingebettet als Kontext
  ↓
LLM generiert Antwort basierend auf Projekt-Kontext

7. Shadow Workspace

Cursor implementiert ein Shadow Workspace Konzept: ein verstecktes Electron-Fenster, das das Projekt spiegelt.

Zweck:

  • AI-generierte Code-Aenderungen sicher testen bevor sie dem User praesentiert werden
  • Language Server Feedback (Type-Checking, Linting) auf vorgeschlagene Aenderungen anwenden
  • Selbst-Verbesserungsschleife: Fehler werden zurueck an das LLM gegeben

Ablauf:

AI generiert Code-Aenderung
  ↓
Shadow Workspace (verstecktes Fenster)
  ├─> Aenderungen anwenden (nicht in echten Dateien)
  ├─> Language Server pruefen (TypeScript, Python, etc.)
  └─> Diagnostics sammeln
        ↓
[Wenn Fehler] → Feedback an LLM → Neuer Versuch
[Wenn OK]     → Aenderung dem User praesentieren

8. Subagenten-Architektur

Seit Januar 2026 unterstuetzt Cursor das Starten spezialisierter Subagenten:

8.1 Subagent-Typen

Typ Zweck Faehigkeiten
generalPurpose Komplexe, mehrstufige Tasks Voller Tool-Zugang, Code-Suche, Ausfuehrung
explore Schnelle Codebase-Exploration Glob, Grep, Read - optimiert fuer Geschwindigkeit
browser-use Browser-basiertes Testing Navigation, Interaktion, Screenshots

8.2 Subagent-Kommunikation

Parent Agent
  ├─> Task(prompt="...", subagent_type="explore")
  │     ├─> Subagent erhaelt eigenen Kontext
  │     ├─> Subagent fuehrt Tools aus
  │     └─> Subagent gibt Ergebnis zurueck (einzelne Message)
  │
  └─> Bis zu 4 Subagenten parallel

Wichtig: Subagenten haben keinen Zugriff auf den Chat-Verlauf des Parent-Agenten. Der Prompt muss alle noetige Information enthalten.

9. Background Agent API

Cursor bietet seit 2026 eine Background Agent API fuer programmatischen Zugriff:

9.1 Authentifizierung

Ueber WorkosCursorSessionToken (Cookie/Environment Variable)

9.2 Endpunkte

Endpunkt Methode Beschreibung
Composer erstellen POST Neuen Background Composer mit Task-Beschreibung starten
Composer auflisten GET Alle laufenden Background Composer abrufen
Composer Details GET Status und Details eines spezifischen Composers
Settings GET User-Einstellungen abrufen

9.3 Programmatischer Zugriff (TypeScript)

import { CursorAPIClient } from 'cursor-api-client';

const client = new CursorAPIClient('session-token');

const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

const composers = await client.listComposers();

9.4 Direkter RPC-Zugriff (Go)

creds, _ := cursor.GetDefaultCredentials()
aiService := cursor.NewAiServiceClient()

model := "gpt-4"
resp, _ := aiService.StreamChat(context.TODO(), cursor.NewRequest(creds, &aiserverv1.GetChatRequest{
    ModelDetails: &aiserverv1.ModelDetails{
        ModelName: &model,
    },
    Conversation: []*aiserverv1.ConversationMessage{
        {
            Text: "Hello, who are you?",
            Type: aiserverv1.ConversationMessage_MESSAGE_TYPE_HUMAN,
        },
    },
}))

for resp.Receive() {
    next := resp.Msg()
    fmt.Printf(next.Text)
}

10. Model-Routing

Cursor verwendet verschiedene Modelle je nach Aufgabentyp:

Aufgabe Modell-Typ Beispiele
Chat / komplexe Analyse Frontier LLM Claude 4.6 Opus, GPT-5.2/5.3, Gemini 3 Pro
Tab Completion Custom Fast Model "Copilot++" (basierend auf Llama 70B)
Fast Apply (Diffs) Spezialisiertes Fine-Tuned Model Optimiert fuer Code-Diffs, >1000 Tokens/s
Embeddings Embedding Model OpenAI Embedding oder Custom

Speculative Decoding: Ein kleineres "Draft"-Modell generiert mehrere Token voraus, die das Hauptmodell parallel verifiziert → signifikant schnellere Inferenz.

11. Sicherheitsmodell

11.1 Terminal Sandbox

Kommandos laufen standardmaessig in einer Sandbox:

  • Erlaubt: Schreiben im Workspace, Lesen im Dateisystem
  • Blockiert: Netzwerk, Git-Write, ignorierte Dateien, USB
  • Erweiterbar: network, git_write, all Permissions

11.2 Privacy Mode

  • Wenn aktiviert: Kein Code wird nach Erfuellung des Requests gespeichert
  • Wenn deaktiviert: Anonymisierte Telemetrie, kein langfristiges Code-Speichern

11.3 Rules System

  • .cursor/rules/ - Projekt-spezifische AI-Verhaltensregeln
  • User Rules - Globale Praeferenzen
  • <system_reminder> Tags - Dynamische Instruktionen (nie sichtbar fuer User)

Quellen und Referenzen