Kurs/rozdział 0425 min

Własni agenci

Profile z własnym promptem, modelem i uprawnieniami — reviewer, dokumentalista, orchestrator.

Czym jest profil agenta

Agent łączy w jednym nazwanym profilu: prompt systemowy, preferowany model (z wariantem), tryb pracy (primary/subagent/all) i zestaw uprawnień. Po co? Żeby agent „recenzenta” fizycznie nie mógł edytować plików, „dokumentalista” nie odpalał shelli, a drogie modele używały tylko tam, gdzie trzeba.

Definicję zapiszesz jako plik Markdown (ciało pliku = prompt systemowy) albo wpis w opencode.json(c). Oba formaty mają te same pola.

Agent w Markdown — .opencode/agents/

Globalnie agenty trafiają do ~/.config/opencode/agents/<nazwa>.md, projektowo do .opencode/agents/. Zagnieżdżenie buduje ID: .opencode/agents/team/reviewer.md to agent team/reviewer.

Użycie: poproś „Użyj subagenta reviewer do przejrzenia moich zmian”, a agent główny odpali dziecko w osobnej sesji i dostanie jego ustalenia.

.opencode/agents/reviewer.md — read-only reviewer

---
description: Recenzuje zmiany pod kątem poprawności i regresji
mode: subagent
model: anthropic/claude-sonnet-4-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Przejrzyj bieżące zmiany. Wyniki wypisz według severity,
z odniesieniami do plików i linii. NIE sugeruj gotowych patchy —
tylko diagnozę i kierunek naprawy.

Agent w JSONC — blok agents

opencode.jsonc — ten sam reviewer w konfiguracji

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "reviewer": {
      "description": "Recenzuje bieżące zmiany",
      "mode": "subagent",
      "system": "Raportuj znalezione problemy według severity.",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

Tryby pracy (mode)

Subagenty ruszają z czystym kontekstem, w sesji podrzędnej (przód albo tło). O tym, kogo wolno odpalać, decydują uprawnienia subagenta rodzica (action: subagent, zasób = ID agenta); dziecko używa WŁASNYCH uprawnień.

mode	Zachowanie
primary	Prowadzi sesję jako główny agent. Domyślne dla nowego własnego agenta.
subagent	Wystartuje tylko jako dziecko przez narzędzie subagent.
all	Zarówno primary, jak i subagent.

Wszystkie pola agenta

Pole	Co robi
description	Cel agenta; dla subagentów obowiązkowe — model wybiera na tej podstawie kogo wezwać
mode	primary \| subagent \| all
model	dostawca/model z opcjonalnym wariantem, np. anthropic/claude-sonnet-4-5#high; subagent bez tego dziedziczy model rodzica
system	Prompt systemowy; nieustywalny podmienia bazowy prompt dostawcy (w Markdown: ciało pliku)
permissions	Uporządkowane reguły action/resource/effect (dokładnie w rozdziale 8)
steps	Limit kroków modelu; na ostatnim kroku narzędzia są odbierane, a agent podsumowuje
hidden	Ukrywa z listy/dialogów — widoczność, NIE bezpieczeństwo
color	Kolor UI, hex, np. #ff6b6b
disabled	true — wyłącza agenta (nawet wbudowanego) w tym punkcie konfiguracji

⚠

Uwaga

Nie używaj przestarzałych pól V1 (temperature, top_p, prompt, tools, maxSteps…). Ustawienia żądań konfiguruje się dziś na dostawcy/modelu/wariancie — pole request w agencie V2 jest przyjmowane, ale jeszcze nie wysyłane.

default_agent i nadpisywanie wbudowanych

Ten sam ID co agent wbudowany = nadpisanie. Reguły agenta DOPISUJĄ się do globalnych permissions i są oceniane później, więc mogą je zawężać/rozszerzać (last match wins).

Zmiana startowego agenta i wzmocnienie build

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan",
  "agents": {
    "build": {
      "permissions": [
        { "action": "shell", "resource": "git push *", "effect": "ask" }
      ]
    },
    "plan": { "disabled": true }
  }
}

Orchestrator — agent, który rządzi subagentami

Dozwolone tylko dwa konkretne subagenty

{
  "agents": {
    "orchestrator": {
      "description": "Planuje pracę i deleguje ją wyspecjalizowanym subagentom",
      "mode": "primary",
      "system": "Nie implementuj samodzielnie. Rozbij zadanie i deleguj: badania do explore, przegląd do reviewer.",
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "explore", "effect": "allow" },
        { "action": "subagent", "resource": "reviewer", "effect": "allow" },
        { "action": "edit", "resource": "*", "effect": "deny" }
      ]
    }
  }
}

✦

Wskazówka

Domyślna głębokość zagnieżdżenia subagentów to 1 — dzieci nie odpalają własnych dzieci (dlatego general ma zabronione subagenty).

Pomysły na agentów do Twojego repo

db-migrations — subagent; zna konwencje migracji, pozwala tylko na edycję packages/db/migrations.
security-scout — subagent z read + grep + websearch; szuka znanych CVE i wycieków sekretów.
docs-writer — primary na dni dokumentacyjne; prompt: „aktualizuj docs/, nie ruszaj src/”.
release-captain — all; łączy się ze skillami release'owymi (permissions skill).