Plik AGENTS.md dla agentów

Agenci AI przed pracą zaglądają do pliku AGENTS.md w katalogu głównym projektu - to zwykły tekst z instrukcjami. Kadraris publikuje gotowy plik z opisem swojego API pod adresem https://kadraris.com/agents.md. Gdy dołożysz go do repozytorium, agent bez twoich tłumaczeń wie, jak użyć klucza, jak zamówić obraz lub wideo przez POST /v1/generate, jak sprawdzić stan zadania, jak rozmawiać z modelami czatu i jak podpiąć serwer MCP.

Zawartość pliku

• adres bazowy https://kadraris.com/v1 i nagłówek Authorization: Bearer $KADRARIS_API_KEY,
• zasady płacenia: blokada środków przed startem, 0 za nieudaną generację, znaczenie kodów 402 i 403,
• katalog (GET /v1/models, GET /v1/models/{id}) i reguła "najpierw schemat, potem input",
• przykłady w curl: obraz, wideo z odpytywaniem, piosenka z tekstem, czat,
• podpisane webhooki,
• ustawienia serwera MCP dla Claude Code, Codex CLI i Cursora,
• tabela błędów oraz uwaga, że POST /v1/generate nie jest idempotentny.

Plik napisany jest po angielsku, bo w tym języku agenci czytają instrukcje najpewniej. Odpowiadać ci będą i tak po polsku, jeśli po polsku do nich piszesz.

Jak ściągnąć go do projektu

Uruchom terminal w katalogu głównym repozytorium.

macOS i Linux

curl -fsSL https://kadraris.com/agents.md -o AGENTS.md

Jeśli AGENTS.md już istnieje, doklej opis Kadrarisa na końcu, zamiast go zastępować:

curl -fsSL https://kadraris.com/agents.md >> AGENTS.md

Windows (PowerShell)

Invoke-WebRequest -Uri "https://kadraris.com/agents.md" `
  -OutFile "AGENTS.md"

Doklejenie do pliku, który już masz:

Invoke-RestMethod -Uri "https://kadraris.com/agents.md" |
  Add-Content -Path "AGENTS.md" -Encoding utf8

Przez przeglądarkę

Wejdź na https://kadraris.com/agents.md, zaznacz wszystko skrótem Ctrl+A, skopiuj i wklej do nowo utworzonego AGENTS.md w projekcie.

Czy plik jest na miejscu

head -5 AGENTS.md

Get-Content AGENTS.md -TotalCount 5

Na samej górze powinna stać linia # AGENTS.md - Kadraris API. Zadaj agentowi pytanie kontrolne: "Jak według AGENTS.md wygenerować obraz w Kadrarisie?". Odpowiedź z POST /v1/generate i ?wait=60 oznacza, że wszystko gra.

Kto czyta AGENTS.md

W Claude Code wystarczy jedna linia:

echo "@AGENTS.md" >> CLAUDE.md

Add-Content -Path "CLAUDE.md" -Value "@AGENTS.md"

Klucz nie trafia do repozytorium

W pliku nie ma żadnego klucza. Agent odczytuje go ze zmiennej KADRARIS_API_KEY, którą ustawiasz jednorazowo:

export KADRARIS_API_KEY="sk-kd-..."

[Environment]::SetEnvironmentVariable(
  "KADRARIS_API_KEY", "sk-kd-...", "User")

Klucz założysz w panelu, w zakładce Klucze API. Koniecznie wpisz mu Limit miesięczny - agent, który może zlecać wideo, powinien mieć nieprzekraczalny pułap wydatków.

Trzymasz klucz w .env? Sprawdź, czy ten plik jest wpisany do .gitignore.

Twoje zasady pod spodem

Pod częścią o API dopisz reguły swojego projektu, na przykład:

## Zasady projektu

- Przed generacją wideo pokaż estimated_cost i czekaj na zgodę.
- Obrazy zapisuj do public/img/ w formacie .webp.
- Obrazy: nano-banana-pro. Wideo: seedance-2.5 w 720p.
- Najwyżej 3 warianty w jednej serii.

Odświeżanie pliku

Kiedy dojdą nowe endpointy albo zmienią się przykłady, pobierz plik jeszcze raz tym samym poleceniem. Własne reguły trzymaj w wydzielonej sekcji i po pobraniu wklej je z powrotem - albo od razu przenieś je do osobnego pliku.

Problemy i naprawa