Agents.md: Jak zaprojektować plik, który uratuje twój projekt AI przed chaosem

W zeszłym miesiącu zespół z polskiego startupu e-commerce odetchnął z ulgą. Po trzech miesiącach walki z niezgodnymi agentami LLM, które działały jak luźne elektrony w atomie, wdrożyli jeden plik. Nie nowy model, nie kolejne API – zwykły dokument Markdown o nazwie agents.md. Efekt? Koszty obsługi klienta spadły o 40%, a developerzy przestali budzić się w nocy z myślą o niezdefiniowanych edge cases.

Dlaczego agents.md zadecyduje o sukcesie twojego projektu AI w 2024 roku?

Case study: Jak polski startup obniżył koszty o 40% dzięki standaryzacji agentów

Firma z Wrocławia, specjalizująca się w automatyzacji obsługi klienta dla sklepów internetowych, miała problem. Każdy z pięciu developerów implementował agenta customer support na swój sposób – różne modele, różne prompty, różne integracje z CRM. Gdy jeden z nich odszedł, nikt nie był w stanie odtworzyć jego konfiguracji. Wprowadzenie agents.md jako centralnego pliku dokumentacji zajęło dwa tygodnie, ale już po miesiącu koszty obsługi spadły z 12 000 PLN do 7 200 PLN miesięcznie [5]. Kluczem nie była magia AI, ale jasne zasady: jeden plik, jedna prawda.

78% zespołów AI nie dokumentuje agentów – czy twój też?

Badanie przeprowadzone na 50 projektach open-source wykazało, że 68% z nich nie ma żadnej dokumentacji agentów [6]. W praktyce oznacza to, że gdy developer opuszcza zespół, wiedza o działaniu agentów znika razem z nim. W polskich realiach, gdzie rotacja w IT jest wysoka (średnio 18 miesięcy na stanowisku [do uzupełnienia przez redakcję]), brak dokumentacji to recepta na chaos. Agents.md nie jest kolejnym biurokratycznym wymogiem – to ubezpieczenie na wypadek odejścia kluczowego członka zespołu.

Czym różni się agents.md od zwykłej dokumentacji?

Tradycyjna dokumentacja opisuje co robi system. Agents.md skupia się na jak działa agent, aby inny developer mógł go odtworzyć w 100%. To nie jest README z ogólnymi założeniami, ale szczegółowy opis:

• ról i uprawnień (np. "Agent może czytać dane z CRM, ale nie może ich modyfikować"),
• narzędzi i API (np. "Integracja z API Allegro w wersji 2.3, endpoint /orders"),
• workflow (np. "Jeśli klient pyta o status zamówienia, agent najpierw sprawdza bazę danych, a dopiero potem odpowiada").

Różnica jest jak między instrukcją obsługi samochodu a schematem silnika. Jedno mówi, że pedał gazu przyspiesza, drugie – jak działa wtrysk paliwa.

Jakie elementy MUSZĄ znaleźć się w agents.md, żeby agent działał jak członek zespołu?

Role i permissions: Jak zdefiniować uprawnienia agenta w stylu GitHub Actions

W agents.md role nie są ogólnikami. Przykład z szablonu CrewAI [2]:

role: "Customer Support Agent"
permissions:
  - read:orders
  - read:customer_data
  - write:responses
  - deny:modify_orders

Dlaczego to ważne? Bo gdy agent ma zbyt szerokie uprawnienia, ryzykujesz wyciek danych. W polskim kontekście, gdzie RODO nakłada surowe kary (do 20 mln EUR lub 4% rocznego obrotu [do uzupełnienia przez redakcję]), precyzyjne definiowanie permisji nie jest opcją – to obowiązek.

Tools i API: Jak opisać integracje, żeby inny developer mógł je odtworzyć

Sekcja tools powinna zawierać:

• nazwę narzędzia (np. "Allegro API"),
• wersję (np. "v2.3"),
• endpointy (np. /orders/{order_id}),
• wymagane klucze API (np. "Zmienna środowiskowa ALLEGRO_API_KEY"),
• przykład użycia (np. "Agent wywołuje endpoint /orders z parametrem status=shipped").

Przykład z przewodnika Hugging Face [4]:

**Tools:**
- Name: CRM API
  Version: 1.2
  Endpoint: `https://api.crm.example.com/customers/{id}`
  Required env vars: `CRM_API_KEY`
  Example: `GET /customers/12345`

Bez tych informacji kolejny developer spędzi 2-3 godziny na reverse-engineeringu kodu, zamiast skupić się na rozwoju.

Workflow: Krok po kroku, jak agent ma podejmować decyzje

Najczęstszy błąd? Opisanie workflow w jednym zdaniu: "Agent odpowiada na pytania klientów". To za mało. Przykład z polskiego e-commerce [5]:

**Workflow:**
1. Agent odbiera wiadomość od klienta.
2. Sprawdza status zamówienia w bazie danych (endpoint `/orders/{id}`).
   - Jeśli status = "shipped", odpowiada: "Twoje zamówienie zostało wysłane [numer przesyłki]".
   - Jeśli status = "processing", odpowiada: "Twoje zamówienie jest w trakcie realizacji. Oczekiwany czas dostawy: [data]".
3. Jeśli status nie jest rozpoznany, agent przekazuje sprawę do operatora.

Dlaczego to działa? Bo zawiera konkretne kroki, warunki i przykłady odpowiedzi. Dzięki temu nawet junior developer zrozumie, jak agent ma działać.

Czy agents.md może być napisany w YAML, JSON, czy tylko w Markdown? Porównanie formatów

Markdown vs. YAML: Który format wybierają polskie firmy i dlaczego?

W Polsce dominuje Markdown [5]. Dlaczego?

• Łatwość edycji: Każdy developer zna Markdown, a YAML wymaga znajomości składni (np. wcięć).
• Integracja z GitHub: Markdown renderuje się automatycznie, co ułatwia przeglądanie zmian w PR.
• Narzędzia: Polskie firmy często korzystają z GitBook lub MkDocs, które lepiej obsługują Markdown niż YAML.

Przykład z szablonu CrewAI [2] pokazuje, że YAML jest czytelny, ale wymaga więcej uwagi:

role: "Data Analyst"
goal: "Analizować dane sprzedażowe i generować raporty"
tools:
  - "Pandas"
  - "SQL"

Markdown jest prostszy:

**Role:** Data Analyst
**Goal:** Analizować dane sprzedażowe i generować raporty
**Tools:**
- Pandas
- SQL

Wybór zależy od zespołu, ale w polskich realiach Markdown wygrywa przez prostotę.

Przykład: Jak wygląda agents.md dla agenta customer support w sklepie internetowym

Oto pełny przykład dla polskiego sklepu internetowego, bazujący na szablonie z DevStyle [5]:

# Customer Support Agent

**Role:** Agent obsługi klienta
**Goal:** Odpowiadać na pytania klientów dotyczące statusu zamówień, zwrotów i produktów
**Permissions:**
- Read: orders, customer_data
- Write: responses
- Deny: modify_orders, delete_data

**Tools:**
- Name: Allegro API
  Version: 2.3
  Endpoint: `https://api.allegro.pl/orders/{id}`
  Required env vars: `ALLEGRO_API_KEY`
- Name: CRM
  Version: 1.2
  Endpoint: `https://crm.example.com/customers/{id}`

**Workflow:**
1. Agent odbiera wiadomość od klienta.
2. Sprawdza status zamówienia w Allegro API.
   - Jeśli status = "shipped", odpowiada: "Twoje zamówienie zostało wysłane. Numer przesyłki: [numer]."
   - Jeśli status = "processing", odpowiada: "Twoje zamówienie jest w trakcie realizacji. Oczekiwany czas dostawy: [data]."
3. Jeśli klient pyta o zwrot, przekazuje sprawę do operatora.

**Examples:**
- Pytanie: "Gdzie jest moje zamówienie #12345?"
  Odpowiedź: "Twoje zamówienie #12345 zostało wysłane 10.05.2024. Numer przesyłki: IN123456789PL."
- Pytanie: "Chcę zwrócić produkt."
  Odpowiedź: "Przekazuję Twoją sprawę do naszego działu zwrotów. Proszę o chwilę cierpliwości."

**Edge Cases:**
- Jeśli klient poda nieistniejący numer zamówienia, agent odpowiada: "Nie znaleziono zamówienia o numerze [numer]. Proszę sprawdzić poprawność danych."
- Jeśli API Allegro zwróci błąd, agent przekazuje sprawę do operatora.

Narzędzia do walidacji: Jak sprawdzić, czy twój plik jest poprawny

1. Dla Markdown:

• MarkdownLint – narzędzie do sprawdzania poprawności składni.
• GitHub Actions – automatyczna walidacja przy pushu do repozytorium.

1. Dla YAML:

• YAML Lint – sprawdza składnię YAML.
• JSON Schema Validator – jeśli używasz JSON.

1. Dla bezpieczeństwa:

• GitGuardian – skanuje pliki pod kątem wrażliwych danych (np. kluczy API).

W Polsce popularne jest też narzędzie Snyk, które integruje się z GitHub i sprawdza pliki pod kątem podatności na ataki [do uzupełnienia przez redakcję].

Jak zintegrować agents.md z istniejącym stackiem technologicznym?

GitHub + agents.md: Jak versionować i udostępniać agentów zespołowi

1. Struktura repozytorium:

```

/project

├── /agents

│ ├── customer_support.md

│ └── data_analyst.md

├── /src

└── README.md

```

1. Versionowanie:

• Plik agents.md powinien być versionowany razem z kodem agenta [4].
• Przy każdej zmianie w agencie aktualizujesz agents.md i commitujesz razem z kodem.

1. Pull Requesty:

• Każda zmiana w agents.md wymaga code review – tak jak kod.
• Przykładowy workflow w GitHub Actions:

```yaml

name: Validate agents.md

on: [push, pull_request]

jobs:

lint:

runs-on: ubuntu-latest

steps:

• uses: actions/checkout@v4
• name: Run markdownlint

run: npx markdownlint-cli2 "agents/*.md"

```

CI/CD dla agentów: Jak automatycznie testować agents.md przed deploymentem

1. Testy jednostkowe dla workflow:

• Napisz testy, które sprawdzają, czy agent działa zgodnie z opisem w agents.md.
• Przykład w Pythonie (pytest):

```python

def test_customer_support_workflow():

agent = CustomerSupportAgent()

response = agent.handle_message("Gdzie jest moje zamówienie #12345?")

assert "numer przesyłki" in response

```

1. Automatyczna walidacja:

• Użyj narzędzi takich jak Great Expectations do testowania danych wejściowych/wyjściowych agenta.

1. Deployment:

• Przed wdrożeniem agenta do produkcji uruchom testy z agents.md jako źródłem prawdy.

Bezpieczeństwo: Jak chronić wrażliwe dane w pliku

1. Nigdy nie umieszczaj kluczy API w pliku:

• Zamiast tego używaj zmiennych środowiskowych lub narzędzi takich jak Vault [5].
• Przykład:

```markdown

Tools:

• Name: Allegro API

Required env vars: ALLEGRO_API_KEY # Nie wpisuj klucza tutaj!

```

1. Placeholdery dla wrażliwych danych:

• Zamiast prawdziwych danych wpisuj [SECRET] i opisuj, gdzie je znaleźć.

1. Skanowanie plików:

• Użyj narzędzi takich jak TruffleHog do skanowania repozytorium pod kątem wycieków.

Najczęstsze błędy w agents.md i jak ich uniknąć – porady od polskich ekspertów

Błąd #1: Zbyt ogólne role – jak doprecyzować zadania agenta

Przykład złego opisu roli:

**Role:** Agent obsługi klienta

Lepszy opis:

**Role:** Agent obsługi klienta ds. statusu zamówień i zwrotów
**Goal:** Odpowiadać na pytania dotyczące statusu zamówień i procesu zwrotów, przekazując sprawy nietypowe do operatora

Dlaczego to ważne? Bo ogólne role prowadzą do niejasności. Developer nie wie, czy agent ma obsługiwać reklamacje, czy tylko statusy zamówień. W jednym z polskich projektów precyzyjne zdefiniowanie roli obniżyło liczbę błędnych odpowiedzi agenta o 30% [3].

Błąd #2: Brak przykładów – dlaczego to zabija produktywność zespołu

Brak przykładów w agents.md wydłuża onboarding nowych developerów o 40% [3]. Przykład, jak powinno to wyglądać:

**Examples:**
- Pytanie: "Kiedy dostanę zamówienie #12345?"
  Odpowiedź: "Twoje zamówienie #12345 zostanie dostarczone 15.05.2024. Numer przesyłki: IN987654321PL."
- Pytanie: "Chcę zwrócić produkt."
  Odpowiedź: "Przekazuję Twoją sprawę do działu zwrotów. Proszę o chwilę cierpliwości."

Bez przykładów developer musi zgadywać, jak agent powinien odpowiadać.

Błąd #3: Ignorowanie edge cases – jak przygotować agenta na nietypowe sytuacje

Edge cases powinny stanowić co najmniej 20% dokumentacji [3]. Przykłady z polskiego e-commerce:

**Edge Cases:**
- Jeśli klient poda nieistniejący numer zamówienia:
  Odpowiedź: "Nie znaleziono zamówienia o numerze [numer]. Proszę sprawdzić poprawność danych."
- Jeśli API Allegro zwróci błąd 500:
  Odpowiedź: "Przepraszamy, wystąpił błąd techniczny. Przekazuję Twoją sprawę do operatora."
- Jeśli klient użyje wulgaryzmów:
  Odpowiedź: "Przepraszamy, ale nie możemy kontynuować rozmowy w takim tonie. Proszę o kontakt z działem obsługi."

Firmy, które ignorują edge cases, raportują 25% więcej incydentów związanych z agentami [3].

Co dalej? Jak wdrożyć agents.md w swoim projekcie już dziś

Krok 1: Wybierz szablon agents.md

1. Dla Markdown:

• Szablon z DevStyle – dostosowany do polskich realiów [5].
• Szablon Hugging Face – prosty i uniwersalny [4].

1. Dla YAML:

• Szablon CrewAI – idealny, jeśli używasz tego frameworka [2].

Krok 2: Przetestuj plik z zespołem – jak przeprowadzić code review

1. Utwórz PR:

• Dodaj plik agents.md do repozytorium i utwórz Pull Request.

1. Przeprowadź code review:

• Sprawdź, czy:
• Role są precyzyjne (nie ogólne).
• Narzędzia i API są dokładnie opisane (wersje, endpointy, klucze).
• Workflow zawiera konkretne kroki i warunki.
• Są przykłady i edge cases.

1. Zbierz feedback:

• Poproś zespół o przetestowanie agenta na podstawie agents.md i zgłoszenie problemów.

Krok 3: Monitoruj i aktualizuj – dlaczego agents.md to living document

1. Automatyczne powiadomienia:

• Ustaw GitHub Actions, aby przypominał o aktualizacji agents.md przy zmianach w kodzie.

1. Regularne przeglądy:

• Co miesiąc sprawdzaj, czy plik jest zgodny z rzeczywistością.

1. Aktualizuj edge cases:

• Gdy pojawi się nowy edge case, dodaj go do dokumentacji.

Agents.md nie jest statycznym plikiem. To żywy dokument, który rośnie razem z projektem. W jednym z polskich startupów regularne aktualizacje pliku zmniejszyły liczbę błędów w produkcji o 35% [6].

Źródła

[1] What makes a good AGENTS.md? — https://www.bensbites.com/p/what-makes-a-good-agentsmd

[2] CrewAI AGENTS.md Template — https://github.com/joaomdmoura/crewAI/blob/main/docs/AGENTS.md

[3] How to Document Your AI Agents Effectively: The AGENTS.md Approach — https://www.linkedin.com/pulse/how-document-your-ai-agents-effectively-agentsmd-approach-kumar/

[4] Documenting AI Agents with AGENTS.md: A Hugging Face Guide — https://huggingface.co/blog/agents-md

[5] Jak dokumentować projekty AI w praktyce? Poradnik dla polskich developerów — https://devstyle.pl/2024/03/15/jak-dokumentowac-projekty-ai-w-praktyce/

[6] Standardizing AI Agent Documentation: A Framework for Reproducibility and Scalability — https://arxiv.org/abs/2311.08789