Jak budować własnych agentów AI: architektura, wzorce i skalowanie

Krok 1: Określ architekturę agenta AI i warstwę sterującą

Architektura agenta AI składa się z dwóch głównych części: modelu i otaczającej go usługi. Usługa obejmuje model, jego narzędzia, pamięć i pozostałe elementy. Działa jako zaprogramowane na stałe, deterministyczne oprogramowanie oparte na logice if/else, zbudowane wokół modelu.

To wyraźne rozróżnienie. Zespoły uczące się budować własnych agentów AI często popełniają błąd, powierzając modelowi wszystkie zadania, co powoduje poważne problemy z niezawodnością.

Takie podejście od razu zawodzi. Model generuje tekst, ale logikę wykonuje otaczająca go usługa. Traktuj więc model jako odizolowany silnik rozumowania, który nie ma dostępu do kodu odpowiedzialnego za kierowanie przepływem pracy.

Usługa zarządza stanem, kierowaniem zadań i obsługą błędów. Model nie podejmuje tych decyzji. Po wdrożeniu takiego rozwiązania w średniej firmie SaaS czas rozwiązywania zgłoszeń skrócił się o 40 procent, ponieważ deterministyczna warstwa prawidłowo kierowała zgłoszeniami zamiast polegać na domysłach modelu.

To kod podejmował decyzje. Przejrzysty schemat przepływu pomaga zobaczyć ten podział. Przepływ wyznacza otaczająca model usługa, a nie model, dlatego potrzebujesz ścisłego planu wdrożenia.

Nie pomijaj deterministycznych warunków logicznych. Anthropic opublikował artykuł opisujący możliwe wzorce projektowe agentów AI, obejmujące cztery podstawowe typy systemów: pojedynczych agentów, procesy sekwencyjne, procesy równoległe oraz ocenę i optymalizację.

Chcesz wiedzieć, jak budować własnych agentów AI, którzy poradzą sobie przy większej skali? Dopasuj wzorzec do problemu. Jeśli każesz jednemu agentowi obsługiwać wieloetapowy proces równoległy, znacznie wydłużysz czas reakcji systemu. Pojedynczy agent dobrze radzi sobie z jednym zadaniem.

• [ ] Określ deterministyczną logikę kierowania zadań
• [ ] Rozplanuj dostęp do narzędzi przez MCP
• [ ] Wybierz model bazowy
• [ ] Zaprojektuj strukturę stanu pamięci
• [ ] Skonfiguruj procedury awaryjne na wypadek błędów

Który wzorzec projektowy pasuje do zastosowania twojego agenta?

Łatwo je debugować, ale mają ograniczony zakres zastosowań. W procesach sekwencyjnych wynik pracy jednego agenta trafia do następnego. To dobrze sprawdza się w liniowych zadaniach, takich jak procesy badawcze wymagające ścisłego wykonywania kolejnych kroków.

W architekturze procesów równoległych grupa agentów AI wykonuje zadania asynchronicznie i jednocześnie, podobnie jak w programowaniu wielowątkowym. Pozwala to znacznie skrócić czas realizacji złożonych zadań. W architekturze oceny i optymalizacji dwa systemy agentowe pracują w powtarzających się cyklach: grupa A wykonuje zadanie, a grupa B ocenia i ulepsza wynik.

Przypomina to programowanie w parach.

Takie podejście daje lepsze wyniki przy pisaniu kodu lub tekstów. Poniższy fragment w Pythonie konfiguruje proces równoległy, w którym agenci działają asynchronicznie. Dzięki temu można uruchomić wielu agentów bez czekania, aż każdy po kolei zakończy pracę.

Przyjrzyj się kodowi. `async def run_agent(task: str):`

# Simulate asynchronous agent task await asyncio.sleep(1)

import asyncio


return f"Result for {task}" async def parallel_workflow(tasks: list[str]): # Agents act asynchronously like multithreading results = await asyncio.gather(*[run_agent(task) for task in tasks])


return results tasks = ["fetch_market_data", "analyze_sentiment", "check_compliance"] results = asyncio.run(parallel_workflow(tasks)) print(results)

Projektując proces, weź pod uwagę te kompromisy. Aby zbudować agenta AI z użyciem Claude, programiści łączą Claude Agent SDK i Agent Skills. Jeśli szukasz sposobu na budowę własnych agentów AI, masz więc dwie główne ścieżki.

Starannie dobierz narzędzia. Możesz użyć Claude Agent SDK, jeśli zależy ci na ścisłej integracji, albo LangGraph do orkiestracji złożonych maszyn stanów.

1. Czas realizacji: Procesy równoległe znacznie skracają łączny czas.
2. Koszt: Procesy równoległe zużywają więcej tokenów na sekundę.
3. Dokładność: Cykle oceny i optymalizacji poprawiają dokładność, ale podwajają zapotrzebowanie na moc obliczeniową.
4. Złożoność: Procesy sekwencyjne najłatwiej debugować.

Krok 2: Wybierz model bazowy i framework do orkiestracji

Sposób budowania agentów z Claude jest prosty: SDK odpowiada za pętlę działania, narzędzia i MCP określają, co agent może zrobić, a Skills określają, jak ma to zrobić. To czytelny podział odpowiedzialności. Claude Agent SDK udostępnia pętlę agenta (zbierz kontekst, wywołaj model, uruchom narzędzie, przekaż wynik z powrotem i powtórz), którą można zaprogramować w Pythonie lub TypeScript.

LangGraph daje większą kontrolę. Pozwala zdefiniować jawne węzły grafu odpowiedzialne za logikę i zbudować ścisłe zabezpieczenia, które powstrzymują model przed niepożądanymi wywołaniami narzędzi.

Warstwa orkiestracji zapewnia niezbędne zabezpieczenia, które utrzymują agentów przy zadaniu. Można je zaprogramować na stałe za pomocą narzędzi takich jak LangGraph albo skonfigurować w narzędziach z interfejsem graficznym, takich jak Cursor Automations. Bez orkiestracji agent może w nieskończoność ponawiać tę samą błędną operację.

Bezpieczne zarządzanie danymi uwierzytelniającymi jest kluczowe. Nigdy nie wpisuj kluczy API na stałe w prompcie systemowym. W systemach produkcyjnych należy przekazywać je podczas działania za pomocą zmiennych środowiskowych.

Do złożonego kierowania przepływem pracy wolimy LangGraph. Wymusza przemyślenie zmian stanu. Claude SDK lepiej sprawdza się natomiast przy szybkim prototypowaniu i zadaniach intensywnie korzystających z narzędzi, które wymagają częstych zmian.

{
 "orchestration": {
 "guardrails": {
 "max_iterations": 5,
 "timeout_seconds": 30
 },
 "secrets_manager": {
 "provider": "aws_secrets_manager",
 "keys": ["ANTHROPIC_API_KEY", "FIRECRAWL_API_KEY"]
 }
 }
}

Krok 3: Wdróż narzędzia, dostęp do internetu i zarządzanie pamięcią

Agenci AI uzyskują dostęp do narzędzi przez MCP (Model Context Protocol), narzędzia CLI i frameworki takie jak LangChain. Umiejętność budowania własnych agentów AI obejmuje też zapewnienie im dostępu do rzeczywistych, aktualnych informacji. Bez niego wiedza agenta ogranicza się do zapisanej pamięci i danych treningowych.

Wbudowane narzędzia do pobierania danych oferowane przez firmy takie jak OpenAI i Anthropic zapewniają jedynie ograniczony dostęp do internetu, dlatego potrzebne są wyspecjalizowane narzędzia, takie jak Firecrawl. Pobieranie surowego HTML marnuje miejsce w kontekście i utrudnia modelowi pracę.

Firecrawl udostępnia trzy główne punkty końcowe do pracy z internetem: /search (wyszukiwanie aktualnych informacji), /scrape (pobieranie stron jako danych strukturalnych lub Markdown) i /interact (otwieranie prawdziwej przeglądarki do klikania przycisków i wypełniania formularzy).

W przypadku typowej strony Firecrawl wyodrębnia około 2,788 tokenów czytelnego Markdown zamiast 38,381 tokenów surowego HTML. Oznacza to o 94 procent mniej tokenów wejściowych niż przy pobieraniu surowego HTML. Bezpośrednio poprawia to wydajność agenta.

Struktura stron internetowych może się zmieniać, a same strony mogą zawierać zbędne elementy nawigacji lub skrypty. Jeśli dostępny jest udokumentowany punkt końcowy zwracający dane strukturalne, wybierz go. Testuj też wyodrębnianie danych na reprezentatywnych stronach i po zmianach układu.

import requests


def search_web(query: str):
    response = requests.post("https://api.firecrawl.dev/v1/search", 
        json={"query": query, "limit": 5},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()


def scrape_site(url: str):
    response = requests.post("https://api.firecrawl.dev/v1/scrape",
        json={"url": url, "formats": ["markdown"]},
        headers={"Authorization": f"Bearer {API_KEY}"})
    return response.json()

Pamięć jest niezbędna w długo działających systemach AI, ponieważ każdy model ma okno kontekstowe o ograniczonej pojemności, które po osiągnięciu limitu trzeba odtworzyć. Okno kontekstowe modelu AI może na przykład mieścić 200,000 tokenów. Po jego zapełnieniu trzeba ponownie zbudować kontekst z użyciem pamięci.

Historię rozmowy i stan zapisuj w zewnętrznej bazie danych. Gdy okno kontekstowe się zapełni, pobierz podsumowanie i istotne fakty, a następnie zbuduj prompt od nowa. Nigdy nie zakładaj, że model pamięta cokolwiek poza danymi, które otrzymał w bieżącym wywołaniu.

Jak zarządzać kosztami, kluczami API i testowaniem?

Jeśli uruchamiasz pięciu agentów jednocześnie, płacisz za pięć wywołań modelu naraz. Pojedynczy agenci kosztują mniej za uruchomienie, ale kończą pracę znacznie później. Trzeba więc wyważyć szybkość i budżet.

Przyjrzyjmy się przykładowym kosztom agenta wsparcia obsługującego 10,000 zgłoszeń miesięcznie. Przy koszcie ręcznej obsługi wynoszącym $5 za zgłoszenie daje to łącznie $50,000. Koszt automatyzacji wygląda inaczej.

Hosting kosztuje $100. Próg rentowności osiągasz niemal od razu. Testowanie warstwy sterującej agenta jest konieczne: zanim wdrożysz cokolwiek na produkcję, zasymuluj awarie narzędzi i dokładnie sprawdź obsługę przekroczenia limitu czasu.

Warstwę sterującą sprawdzamy za pomocą deterministycznych przypadków testowych, a model oceniamy zestawami testów probabilistycznych. Nigdy nie wdrażamy agenta bez sprawdzenia, jak radzi sobie z błędami. Nie upychaj wszystkich instrukcji w promptach systemowych.

Agent Skills to foldery z plikiem SKILL.md, które uczą agenta specjalistycznych zadań. Są ładowane w miarę potrzeby, dzięki czemu nie zajmują niepotrzebnie okna kontekstowego. Jeśli chcesz opanować tworzenie własnych agentów AI, oddziel od siebie poszczególne odpowiedzialności.

Mniej oczywisty wniosek: dlaczego wiedza o procedurach powinna trafiać do Skills

Model tworzenia agentów Claude jest prosty: SDK odpowiada za pętlę działania, narzędzia i MCP określają, co agent może zrobić, a Skills uczą go, jak to zrobić. Narzędzia są czasownikami, Skills są instrukcjami. Gdy umieszczasz wszystkie wskazówki w prompcie systemowym, marnujesz miejsce w kontekście: model czyta instrukcje, których nie potrzebuje do bieżącego zadania.

Rozwiązaniem jest stopniowe udostępnianie informacji. Agent ładuje plik SKILL.md dopiero wtedy, gdy ma wykonać dane zadanie. Dzięki temu oszczędza miejsce w oknie kontekstowym i rzadziej halucynuje.

Agenci stają się też modułowi: możesz zaktualizować skill bez zmian w głównej logice orkiestracji.