Superagent

Instalacja Superagent self-hosted: klonujesz repozytorium: git clone https://github.com/homanp/superagent. Kopiujesz plik konfiguracji: cp .env.example .env. Edytujesz .env: wpisujesz klucze API (OPENAI_API_KEY lub ANTHROPIC_API_KEY), konfigurację bazy danych i JWT secret. Uruchamiasz: docker-compose up -d. Superagent startuje na http://localhost:3000 (API) i http://localhost:3001 (dashboard). Tworzysz pierwszego agenta przez API: POST /api/v1/agents z body: name, description, llm (model), tools (lista narzędzi). Dostajesz agent_id. Wywołujesz agenta: POST /api/v1/agents/{agent_id}/invoke z pytaniem. Wymagania serwera: 2 GB RAM, Docker, Docker Compose. Dla produkcji: użyj zewnętrznego PostgreSQL (Supabase, Render), skonfiguruj Nginx jako reverse proxy z SSL. Pierwsze uruchomienie zajmuje 5-10 minut przy pobieraniu obrazów Docker.

RAG w Superagent: tworzysz agenta z włączonym dokumentami. Uploadujesz dokumenty przez API: POST /api/v1/documents z plikiem (PDF, DOCX, TXT, CSV, MD). Superagent automatycznie: parsuje dokument, dzieli na chunki, tworzy embeddingi (OpenAI text-embedding-ada-002 lub podobny), zapisuje w wektorowej bazie danych. Linkujesz dokument do agenta: POST /api/v1/agents/{agent_id}/documents z document_id. Gdy użytkownik zadaje pytanie agentowi, Superagent automatycznie: embeduje pytanie, szuka najbliszcze fragmenty dokumentów, dołącza je jako kontekst do promptu LLM, generuje odpowiedź. Wiele dokumentów: możesz podpiąć dowolną liczbę dokumentów do agenta. Obsługiwane formaty: PDF, DOCX, TXT, CSV, Markdown, URL (strony internetowe). Praktyczny przypadek: FAQ firmy w PDF → agent odpowiada na pytania klientów z cytowaniem źródeł.

Superagent ma gotowe narzędzia które agent może autonomicznie wywoływać. Wbudowane tools: Search (wyszukiwanie w internecie przez Brave Search lub SerpAPI), Code Executor (uruchamia Python code i zwraca wynik), Browser (otwiera URL i ekstraktuje treść), OpenAPI (wywołuje dowolne API przez OpenAPI spec), Metaphor Search (wyszukiwanie semantyczne). Custom tools: możesz definiować własne narzędzia przez OpenAPI schema — jeśli masz własne API z dokumentacją OpenAPI, Superagent automatycznie wie jak go używać. Integracja z zewnętrznymi API: agenty mogą wywoływać Twoje własne endpointy (np. CRM, baza produktów, ERP) jako narzędzia — agent decyduje kiedy wywołać które narzędzie na podstawie pytania użytkownika. Definiowanie narzędzia: POST /api/v1/tools z name, description (opis dla LLM kiedy użyć), returnDirect (czy zwrócić wynik bezpośrednio czy przetworzyć LLM). Dobrze opisane narzędzia (description) są kluczowe dla trafnego użycia przez agenta.

Trzy open source narzędzia do agentów AI z różnymi podejściami. Superagent wygrywa: gotowym REST API i dashboardem bez pisania kodu zarządczego, łatwością deploymentu przez Docker i możliwością zarządzania wieloma agentami przez panel. Najlepszy gdy chcesz szybko zbudować i udostępnić agenta przez API bez pisania całej infrastruktury. LangChain wygrywa: elastycznością i możliwościami — największy framework agentów z największą społecznością, docsami i integracjami. Możesz zbudować dokładnie to co chcesz, ale piszesz więcej kodu. Najlepszy dla zaawansowanych zastosowań wymagających pełnej kontroli. CrewAI wygrywa: multi-agent orchestration — specjalizuje się w koordynacji wielu agentów w rolach (researcher, writer, reviewer). Najlepszy dla workflow gdzie wiele AI agentów współpracuje nad jednym zadaniem. Wybór: szybkie REST API dla agentów → Superagent. Pełna elastyczność w Pythonie → LangChain. Wiele agentów w rolach → CrewAI.

Zabezpieczenie Superagent w produkcji: uwierzytelnianie — Superagent używa JWT tokenów, zawsze wymagaj tokena dla każdego API call. Nie udostępniaj publicznie endpointu bez autoryzacji. HTTPS: nginx jako reverse proxy z certyfikatem Let's Encrypt (Certbot) — wszystkie requesty zaszyfrowane. Rate limiting: skonfiguruj w nginx limit_req_zone żeby zapobiec nadużyciom i nieoczekiwanym rachunkom za API. Bezpieczeństwo kluczy API: przechowuj OPENAI_API_KEY i ANTHROPIC_API_KEY w .env poza repozytorium Git (.gitignore), używaj secrets managera (HashiCorp Vault, AWS Secrets Manager). Limit wydatków: ustaw hard limit w panelu OpenAI/Anthropic na kwotę miesięczną — nieoczekiwane pętle agentów mogą generować duże rachunki. Logowanie: włącz logowanie wszystkich requestów API (user input + agent output) do bazy danych — potrzebne do debugowania i audytu. Backup: codzienny backup PostgreSQL bazy danych z konfiguracją agentów i dokumentów.