File size: 20,282 Bytes

0dbc9de

---
title: Agenten
description: Konfigurieren und verwenden Sie spezielle Agenten.
---

Agenten sind spezialisierte AI-Assistenten, die für bestimmte Aufgaben und Arbeitsabläufe konfiguriert werden können. Sie ermöglichen Ihnen die Erstellung gezielter Werkzeuge mit benutzerdefinierten Eingabeaufforderungen, Modellen und Werkzeugzugriff.

:::tip
Verwenden Sie den Planagenten, um Code zu analysieren und Vorschläge zu überprüfen, ohne Codeänderungen vorzunehmen.
:::

Sie können während einer Sitzung zwischen Agenten wechseln oder sie mit der Erwähnung `@` aufrufen.

---

## Typen

Es gibt zwei Arten von Agenten in OpenCode; Primäragenten und Subagenten.

---

### Primäragenten

Primäragenten sind die Hauptassistenten, mit denen Sie direkt interagieren. Sie können sie mit der **Tabulatortaste** oder Ihrer konfigurierten Tastenkombination `switch_agent` durchblättern. Diese Agenten kümmern sich um Ihr Hauptgespräch. Der Werkzeugzugriff wird über Berechtigungen konfiguriert – zum Beispiel sind bei „Build“ alle Werkzeuge aktiviert, während „Plan“ eingeschränkt ist.

:::tip
Sie können die **Tabulatortaste** verwenden, um während einer Sitzung zwischen primären Agenten zu wechseln.
:::

OpenCode verfügt über zwei integrierte Primäragenten: **Build** und **Plan**. Auch
Schauen wir uns diese unten an.

---

### Build

_Modus_: `primary`

Build ist der **Standard**-Primäragent mit allen aktivierten Tools. Dies ist der Standardagent für Entwicklungsarbeiten, bei dem Sie vollen Zugriff auf Dateioperationen und Systembefehle benötigen.

---

### Plan

_Modus_: `primary`

Ein eingeschränkter Agent, der für Planung und Analyse entwickelt wurde. Wir verwenden ein Berechtigungssystem, um Ihnen mehr Kontrolle zu geben und unbeabsichtigte Änderungen zu verhindern.
Standardmäßig sind alle folgenden Elemente auf `ask` gesetzt:

- `file edits`: Alle Schreibvorgänge, Patches und Bearbeitungen
- `bash`: Alle Bash-Befehle

Dieser Agent ist nützlich, wenn Sie möchten, dass LLM Code analysiert, Änderungen vorgeschlagen oder Pläne erstellt werden, ohne tatsächliche Änderungen an Ihrer Codebasis vorzunehmen.

---

### General

_Modus_: `subagent`

Ein Allzweckagent zur Recherche komplexerer Fragen und zur Ausführung mehrstufiger Aufgaben. Verfügt über vollständigen Zugriff auf das Tool (außer Todo), sodass bei Bedarf Dateiänderungen vorgenommen werden können. Verwenden Sie Matrizen, um mehrere Arbeitseinheiten parallel auszuführen.

---

### Explore

_Modus_: `subagent`

Ein schneller, schreibgeschützter Agent zum Erkunden von Codebasen. Dateien können nicht geändert werden. Verwenden Sie dies, wenn Sie Dateien schnell anhand von Mustern finden, Code nach Schlüsselwörtern durchsuchen oder Fragen zur Codebasis beantworten müssen.

---

### Scout

_Modus_: `subagent`

Ein schreibgeschützter Agent für externe Dokumentation und Dependency-Recherche. Verwenden Sie ihn, wenn Sie ein Dependency-Repository in den von OpenCode verwalteten Cache klonen, den Quellcode einer Bibliothek untersuchen oder lokalen Code mit Upstream-Implementierungen abgleichen müssen, ohne Ihren Workspace zu verändern.

---

### Compaction

_Modus_: `primary`

Versteckter Systemagent, der lange Kontext in einer kleineren Zusammenfassung komprimiert. Es wird bei Bedarf automatisch ausgeführt und ist im UI nicht auswählbar.

---

### Title

_Modus_: `primary`

Versteckter Systemagent, der kurze Sitzungstitel generiert. Es läuft automatisch und ist im UI nicht auswählbar.

---

### Summary

_Modus_: `primary`

Versteckter Systemagent, der Sitzungszusammenfassungen erstellt. Es läuft automatisch und ist im UI nicht auswählbar.

---

## Verwendung

1. Verwenden Sie für primäre Agenten die **Tabulatortaste**, um während einer Sitzung durch sie zu blättern. Sie können auch Ihre konfigurierte `switch_agent`-Tastenkombination verwenden.

2. Subagenten können aufgerufen werden:
   - **Automatisch** durch primäre Agenten für spezielle Aufgaben basierend auf ihren Beschreibungen.
   - Manuell durch **@ Erwähnung** eines Subagenten in Ihrer Nachricht. Zum Beispiel.

     ```txt frame="none"
     @general help me search for this function
     ```

3. **Navigation zwischen Sitzungen**: Wenn Subagenten ihre eigenen untergeordneten Sitzungen erstellen, können Sie zwischen der übergeordneten Sitzung und allen untergeordneten Sitzungen sorgfältig handeln, indem Sie Folgendes verwenden:
   - **\<Leader>+Rechts** (oder Ihre konfigurierte `session_child_cycle`-Tastenkombination), um vorwärts durch Parent → Child1 → Child2 → ... → Parent zu blättern
   - **\<Leader>+Links** (oder Ihre konfigurierte `session_child_cycle_reverse`-Tastenkombination), um rückwärts durch Parent ← Child1 ← Child2 ← ... ← Parent zu blättern

   Dadurch können Sie nahtlos zwischen der Hauptkonversation und der spezialisierten Subagentenarbeit wechseln.

---

## Konfiguration

Sie können die integrierten Agenten anpassen oder über die Konfiguration eigene erstellen. Agenten können auf zwei Arten konfiguriert werden:

---

### JSON

Konfigurieren Sie Agenten in Ihrer `opencode.json`-Konfigurationsdatei:

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}
```

---

### Markdown

Sie können Agenten auch mithilfe von Markdown-Dateien definieren. Platzieren Sie sie in:

- Global: `~/.config/opencode/agents/`
- Pro Projekt: `.opencode/agents/`

```markdown title="~/.config/opencode/agents/review.md"
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
```

Der Name der Markdown-Datei wird zum Agentennamen. Beispielsweise erstellte `review.md` einen `review`-Agenten.

---

## Optionen

Schauen wir uns diese Konfigurationsmöglichkeiten im Detail an.

---

### Beschreibung

Verwenden Sie die Option `description`, um eine kurze Beschreibung darüber bereitzustellen, was der Agent tut und wann er verwendet werden soll.

```json title="opencode.json"
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}
```

Dies ist eine **erforderliche** Konfigurationsoption.

---

### Temperatur

Steuern Sie die Zufälligkeit und Kreativität der Antworten von LLM mit der `temperature`-Konfiguration.

Höchste Werte machen die Antworten fokussierter und deterministischer, während höhere Werte die Kreativität und Variabilität steigern.

```json title="opencode.json"
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}
```

Temperaturwerte liegen typischerweise zwischen 0.0 und 1.0:

- **0.0-0.2**: Sehr fokussierte und deterministische Antworten, ideal für Code-Analyse und Planung
- **0.3-0.5**: Ausgewogene Antworten mit etwas Kreativität, gut für allgemeine Entwicklungsaufgaben
- **0.6-1.0**: Kreativere und vielfältigere Antworten, nützlich für Brainstorming und Erkundung

```json title="opencode.json"
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}
```

Wenn keine Temperatur angegeben ist, verwendet OpenCode modellspezifische Standardwerte; typischerweise 0 für die meisten Modelle, 0.55 für Qwen-Modelle.

---

### Schritte

Steuern Sie die maximale Anzahl an Agenteniterationen, die ein Agent durchführen kann, bevor er gezwungen wird, nur mit Text zu antworten. Dadurch können Benutzer, die die Kosten kontrollieren möchten, ein Limit für Agentenaktionen festlegen.

Wenn dies nicht festgelegt ist, iteriert der Agent weiter, bis das Modell den Stopp beschließt oder der Benutzer die Sitzung unterbricht.

```json title="opencode.json"
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}
```

Wenn das Limit erreicht ist, erhält der Agent eine spezielle Systemaufforderung, die ihn anweist, mit einer Zusammenfassung seiner Arbeit und empfohlenen verbleibenden Aufgaben zu antworten.

:::caution
Das alte Feld `maxSteps` ist veraltet. Verwenden Sie stattdessen `steps`.
:::

---

### Deaktivieren

Auf `true` setzen, um den Agenten zu deaktivieren.

```json title="opencode.json"
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}
```

---

### Prompt

Geben Sie mit der `prompt`-Konfiguration eine benutzerdefinierte Systemaufforderungsdatei für diese Agenten an. Die Eingabeaufforderungsdatei sollte Anweisungen enthalten, die speziell auf den Zweck des Agenten zugeschnitten sind.

```json title="opencode.json"
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}
```

Dieser Pfad ist relativ zum Speicherort der Konfigurationsdatei. Dies funktioniert sowohl für die globale OpenCode-Konfiguration als auch für die projektspezifische Konfiguration.

---

### Modell

Verwenden Sie die `model`-Konfiguration, um das Modell für diese Agenten zu überschreiben. Nützlich für die Verwendung verschiedener Modelle, die für verschiedene Aufgaben optimiert sind. Zum Beispiel ein schnelleres Modell für die Planung, ein leistungsfähigeres Modell für die Umsetzung.

:::tip
Wenn Sie kein Modell angeben, verwenden Sie den primären Agenten [model globally configured](/docs/config#models), während die Subagenten das Modell des primären Agenten verwenden, der den Subagenten aufgerufen hat.
:::

```json title="opencode.json"
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}
```

Die Modell-ID in Ihrer OpenCode-Konfiguration verwendet das Format `provider/model-id`. Wenn Sie beispielsweise [OpenCode Zen](/docs/zen) verwenden, würden Sie `opencode/gpt-5.1-codex` für GPT 5.1 Codex verwenden.

---

### Werkzeuge

Steuern Sie mit der `tools`-Konfiguration, welche Tools in diesem Agent verfügbar sind. Sie können bestimmte Tools aktivieren oder deaktivieren, indem Sie sie auf `true` oder `false` setzen.

```json title="opencode.json" {3-6,9-12}
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}
```

:::note
Die agentenspezifische Konfiguration überschreibt die globale Konfiguration.
:::

Sie können Platzhalter auch verwenden, um mehrere Werkzeuge gleichzeitig zu steuern. So deaktivieren Sie beispielsweise alle Tools von einem MCP-Server:

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}
```

[Learn more about tools](/docs/tools).

---

### Berechtigungen

Sie können Berechtigungen konfigurieren, um zu verwalten, welche Aktionen ein Agent ausführen kann. Derzeit können die Berechtigungen für die Tools `edit`, `bash` und `webfetch` wie folgt konfiguriert werden:

- `"ask"` – Bitten Sie um Genehmigung, bevor Sie das Tool ausführen
- `"allow"` – Alle Vorgänge ohne Genehmigung zulassen
- `"deny"` – Deaktivieren Sie das Tool

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}
```

Sie können diese Berechtigungen pro Agent überschreiben.

```json title="opencode.json" {3-5,8-10}
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}
```

Sie können Berechtigungen auch in Markdown-Agenten festlegen.

```markdown title="~/.config/opencode/agents/review.md"
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---

Only analyze code and suggest changes.
```

Sie können Berechtigungen für bestimmte Bash-Befehle festlegen.

```json title="opencode.json" {7}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}
```

Dies kann ein Glob-Muster annehmen.

```json title="opencode.json" {7}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}
```

Und Sie können den Platzhalter `*` auch verwenden, um Berechtigungen für alle Befehle zu verwalten.
Da die letzte übereinstimmende Regel Vorrang hat, setzen Sie zuerst den Platzhalter `*` und danach bestimmte Regeln.

```json title="opencode.json" {8}
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}
```

[Learn more about permissions](/docs/permissions).

---

### Modus

Steuern Sie den Modus des Agenten mit der `mode`-Konfiguration. Mit der Option `mode` wird festgelegt, wie der Agent verwendet werden kann.

```json title="opencode.json"
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}
```

Die Option `mode` kann auf `primary`, `subagent` oder `all` gesetzt werden. Wenn kein `mode` angegeben ist, wird standardmäßig `all` verwendet.

---

### Versteckt

Verstecken Sie einen Subagenten im Autovervollständigungsmenü `@` mit `hidden: true`. Nützlich für interne Subagenten, die nur programmgesteuert von anderen Agenten über das Task-Tool aufgerufen werden sollten.

```json title="opencode.json"
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}
```

Dies wirkt sich nur auf die Benutzersichtbarkeit im Autovervollständigungsmenü aus. Versteckte Agenten können weiterhin vom Modell über das Aufgabentool aufgerufen werden, sofern die Berechtigungen dies zulassen.

:::note
Gilt nur für `mode: subagent`-Agenten.
:::

---

### Task-Berechtigungen

Steuern Sie, welche Subagenten ein Agent über das Task-Tool mit `permission.task` aufrufen kann. Verwendet Glob-Muster für eine flexible Zuordnung.

```json title="opencode.json"
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}
```

Bei der Einstellung `deny` wird der Subagent vollständig aus der Beschreibung des Aufgabentools entfernt, sodass das Modell nicht versucht, ihn aufzurufen.

:::tip
Die Regeln werden der Reihe nach ausgewertet und die **letzte übereinstimmende Regel gewinnt**. Im obigen Beispiel entspricht `orchestrator-planner` sowohl `*` (verweigern) als auch `orchestrator-*` (zulassen), aber da `orchestrator-*` nach `*` kommt, ist das Ergebnis `allow`.
:::

:::tip
Benutzer können jeden Subagenten immer direkt über das Autovervollständigungsmenü `@` aufrufen, auch wenn die Aufgabenberechtigungen des Agenten dies verweigern würden.
:::

---

### Farbe

Passen Sie das visuelle Erscheinungsbild des Agenten im UI mit der Option `color` an. Dies wirkt sich darauf aus, wie der Agent in der Benutzeroberfläche angezeigt wird.

Verwenden Sie eine gültige Hex-Farbe (z. B. `#FF5733`) oder Themenfarbe: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`.

```json title="opencode.json"
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}
```

---

### Top P

Steuern Sie die Antwortvielfalt mit der Option `top_p`. Alternative zur Temperatur zur Kontrolle des Zufalls.

```json title="opencode.json"
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}
```

Die Werte reichen von 0.0 bis 1.0. Niedrigere Werte sind fokussierter, höhere Werte vielfältiger.

---

### Zusätzliche Optionen

Alle anderen Optionen, die Sie in Ihrer Agentenkonfiguration angeben, werden als Modelloptionen **direkt** an den Anbieter weitergeleitet. Dadurch können Sie anbieterspezifische Funktionen und Parameter nutzen.

Mit den Argumentationsmodellen von OpenAI können Sie beispielsweise den Argumentationsaufwand steuern:

```json title="opencode.json" {6,7}
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}
```

Diese zusätzlichen Optionen sind modell- und anbieterspezifisch. Überprüfen Sie die Dokumentation Ihres Anbieters auf verfügbare Parameter.

:::tip
Führen Sie `opencode models` aus, um eine Liste der verfügbaren Modelle anzubieten.
:::

---

## Agenten erstellen

Mit dem folgenden Befehl können Sie neue Agenten erstellen:

```bash
opencode agent create
```

Dieser interaktive Befehl führt zu Folgendem:

1. Fragen Sie, wo der Agent gespeichert werden soll. global oder projektspezifisch.
2. Beschreibung dessen, was der Agent tun soll.
3. Generieren Sie eine entsprechende Systemaufforderung und -kennung.
4. Hier können Sie auswählen, auf welche Tools der Agent zugreifen kann.
5. Erstellen Sie abschließend eine Markdown-Datei mit der Agentenkonfiguration.

---

## Anwendungsfälle

Hier sind einige häufige Anwendungsfälle für verschiedene Agenten.

- **Build-Agent**: Vollständige Entwicklungsarbeit mit allen aktivierten Tools
- **Planagent**: Analyse und Planung ohne Änderungen
- **Review-Agent**: Codeüberprüfung mit schreibgeschütztem Zugriff plus Dokumentationstools
- **Debug-Agent**: Konzentriert sich auf die Untersuchung mit aktivierten Bash- und Lesetools
- **Docs-Agent**: Schreiben von Dokumentationen mit Dateioperationen, aber ohne Systembefehle

---

## Beispiele

Hier sind einige Beispielagenten, die für Sie nützlich sein könnten.

:::tip
Haben Sie einen Agenten, den Sie gerne teilen möchten? [Reichen Sie einen PR ein](https://github.com/anomalyco/opencode).
:::

---

### Dokumentationsagent

```markdown title="~/.config/opencode/agents/docs-writer.md"
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language
```

---

### Sicherheitsprüfer

```markdown title="~/.config/opencode/agents/security-auditor.md"
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---

You are a security expert. Focus on identifying potential security issues.

Look for:

- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues
```