StellarBase
Zpět na blog
Tutoriál 20. března 2026 7 min čtení

Stavba prvního AI agenta se StellarBase

Krok za krokem od nuly k produkčnímu AI agentovi ukotvenému ve vašich datech. Včetně citací, workflows a access control.

Co jsou AI agenti?

AI agent je víc než chatbot. Zatímco chatbot odpovídá na jednotlivé zprávy izolovaně, agent má přístup k nástrojům, datovým zdrojům a workflows. Umí vytáhnout informace z vaší knowledge base, plnit vícekrokové instrukce a podnikat akce na základě svého uvažování.

Ve StellarBase jsou agenti rozhraním mezi vašimi uživateli a vašimi daty. Kombinují konverzační schopnost velkých jazykových modelů s ukotvenou znalostí z vašich kolekcí dokumentů — pohánějí je DSM engine. Každá odpověď je podložená skutečnými zdroji z vašich dat, s citacemi ukazujícími na přesný dokument, stránku a pasáž.

Tady je, co odlišuje agenty StellarBase od základního „chat with your docs” setupu:

  • Retrieval poháněný DSM — agenti používají znalostní graf, ne jen vektorové vyhledávání, k nalezení relevantního kontextu. Sledují vztahy napříč dokumenty pro stavbu kompletních odpovědí
  • Povinné citace — každé faktické tvrzení odkazuje zpět na zdroj. Pokud agent zdroj nenajde, řekne to, místo aby halucinoval
  • Access control — agenti vidí jen data, ke kterým mají autorizaci. Tag-based oprávnění zajistí, že citlivé dokumenty zůstanou omezené
  • Workflow integrace — agenti mohou být zabudovaní do automatizovaných workflows, spouštěných webhooky a řetězení s dalšími agenty

Krok 1: Vytvořte agenta

Každý agent začíná konfigurací, která definuje jeho jméno, účel, model a chování. Agenty lze vytvářet přes StellarBase UI nebo přes API. Použijeme API, protože je explicitnější o tom, co se děje.

# Create a new agent
curl -X POST https://app.stellarbase.ai/api/v1/agents 
  -H "Authorization: Bearer sb_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Support Agent",
    "description": "Answers customer questions using product docs",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You are a helpful support agent. Answer questions based on the provided documentation. Always cite your sources.",
    "temperature": 0.3,
    "max_tokens": 1024
  }'

API vrátí ID agenta, které použijete pro všechny následné operace:

{
	"id": "agent_abc123",
	"name": "Support Agent",
	"status": "created",
	"created_at": "2026-03-20T10:00:00Z"
}

Pár poznámek ke konfiguraci:

  • model — jakýkoli model dostupný přes StellarCloud, nebo lokální model, pokud self-hostujete. Agent ho použije pro veškeré uvažování a generování odpovědí
  • system_prompt — tohle je osobnost a instrukce vašeho agenta. Buďte specifičtí ohledně toho, co má a nemá dělat. Přidejte instrukce ohledně chování citací
  • temperature — nižší hodnoty (0,1-0,3) produkují konzistentnější, faktické odpovědi. Vyšší hodnoty (0,7-1,0) umožňují kreativnější odpovědi. Pro znalostní agenty držte nízko

Krok 2: Připojte datové zdroje

Agent bez dat je jen wrapper kolem LLM. Síla agentů StellarBase je v jejich připojení ke kolekcím dokumentů. Kolekce mohou obsahovat PDF, Word dokumenty, Markdown soubory, HTML stránky, Confluence exporty nebo jakýkoli textový formát.

# Connect a data source to the agent
curl -X POST https://app.stellarbase.ai/api/v1/agents/agent_abc123/sources 
  -H "Authorization: Bearer sb_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "source_type": "collection",
    "source_id": "col_docs_456",
    "permissions": "read",
    "search_mode": "dsm"
  }'

Parametr search_mode je důležitý. Nastavení na dsm zapne plnou Dynamic Semantic Module pipelinu — rozpoznávání entit, traversal vztahů a retrieval poháněný grafem. To dává výrazně lepší výsledky než základní vektorové vyhledávání, zvlášť u otázek vyžadujících informace z více dokumentů.

K jednomu agentovi můžete připojit více kolekcí. Například support agent může mít přístup k produktové dokumentaci, FAQ článkům a release notes — každá jako samostatná kolekce s jiným plánem aktualizací.

Krok 3: Otestujte agenta

S připojenými daty je agent připravený odpovídat na otázky. Pošlete testovací zprávu pro ověření správné funkce:

# Send a test message
curl -X POST https://app.stellarbase.ai/api/v1/agents/agent_abc123/chat 
  -H "Authorization: Bearer sb_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "message": "How do I reset my password?",
    "include_citations": true
  }'

Odpověď obsahuje odpověď agenta spolu s citacemi ukazujícími na přesné zdroje:

{
	"response": "To reset your password, go to Settings > Security > Change Password. Enter your current password, then your new password twice. Click Save. If you have forgotten your current password, click 'Forgot Password' on the login page to receive a reset link via email.",
	"citations": [
		{
			"text": "Navigate to Settings > Security > Change Password",
			"source": "user-guide.pdf",
			"page": 14,
			"confidence": 0.94
		},
		{
			"text": "Forgot Password link sends a reset email within 2 minutes",
			"source": "faq.md",
			"section": "Account Access",
			"confidence": 0.91
		}
	],
	"tokens_used": 284
}

Každá citace obsahuje zdrojový dokument, polohu (číslo stránky nebo sekci) a confidence skóre. Confidence skóre indikuje, jak silně zdroj podporuje tvrzení — skóre nad 0,8 je vysoká důvěra, 0,6-0,8 střední, a pod 0,6 se agent obvykle zdrží tvrzení.

Tipy na testování

  • Ptejte se otázky, jejichž odpověď znáte — ověřte, že agent vrací správné informace s adekvátními citacemi
  • Ptejte se otázky mimo jeho znalost — ověřte, že agent přizná, když něco neví, místo aby halucinoval
  • Ptejte se multi-hop otázky — otázky vyžadující kombinaci informací z více dokumentů. Tady DSM září
  • Zkuste adversariální prompty — řekněte agentovi, ať ignoruje své instrukce nebo si vymýšlí. Ověřte, že zůstává ukotvený

Krok 4: Nakonfigurujte access control

V produkci téměř jistě chcete omezit, co každý agent vidí. StellarBase používá tag-based access control — každý dokument v kolekci může mít tagy, a agenty lze nakonfigurovat tak, aby přistupovali jen k dokumentům s konkrétními tagy.

# Set access control rules
curl -X PUT https://app.stellarbase.ai/api/v1/agents/agent_abc123/access 
  -H "Authorization: Bearer sb_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "rules": [
      {
        "collection": "col_docs_456",
        "allowed_tags": ["public", "support"],
        "denied_tags": ["internal", "confidential"]
      },
      {
        "collection": "col_kb_789",
        "allowed_tags": ["*"],
        "denied_tags": ["hr-only"]
      }
    ]
  }'

Tahle konfigurace zajistí, že support agent může vidět jen dokumenty otagované jako „public” nebo „support” v docs kolekci a vše kromě dokumentů „hr-only” v knowledge base. Pokud uživatel položí otázku, kterou by šlo zodpovědět jen pomocí omezeného dokumentu, agent odpoví, jako by ten dokument neexistoval.

Access control se vynucuje na úrovni retrieval, ne na úrovni odpovědi. Omezené dokumenty se nikdy nedostanou do LLM kontextu, což znamená, že není riziko úniku informací přes prompt injection nebo jiné útoky.

Krok 5: Přidejte do workflows

Agenti se stávají skutečně mocnými, když jsou zabudovaní do automatizovaných workflows. Místo čekání, až někdo pošle zprávu, agent může být spouštěn automaticky událostmi — novým support ticketem, uploadem dokumentu, naplánovanou úlohou.

# Add agent to a workflow
curl -X POST https://app.stellarbase.ai/api/v1/workflows 
  -H "Authorization: Bearer sb_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Support Ticket Triage",
    "trigger": "webhook",
    "steps": [
      {
        "type": "agent",
        "agent_id": "agent_abc123",
        "input": "Classify this ticket: {{ticket.subject}} - {{ticket.body}}",
        "output_key": "classification"
      },
      {
        "type": "condition",
        "if": "classification.urgency == high",
        "then": "notify_oncall",
        "else": "add_to_queue"
      }
    ]
  }'

Tohle workflow se spouští, kdykoli přijde nový support ticket přes webhook. Agent ticket klasifikuje a podle úrovně urgentnosti buď notifikuje on-call tým, nebo přidá do běžné fronty. Žádný lidský zásah pro krok triage.

Workflows mohou řetězit více agentů. Například:

  • Agent 1 klasifikuje příchozí požadavek (support, sales, billing)
  • Agent 2 sepíše odpověď pomocí relevantní knowledge base
  • Agent 3 zreviduje draft kvůli přesnosti a compliance
  • Finální výstup jde k člověku ke schválení před odesláním

Citace a ukotvení

Ukotvení je to, co odlišuje užitečné AI agenty od nespolehlivých. Každá odpověď agenta StellarBase je ukotvená ve vašich datech, což znamená:

  • Každé faktické tvrzení je citované — agent atribuuje každý kus informace ke konkrétnímu zdroji se jménem dokumentu, polohou a confidence
  • Žádné halucinace záměrně — když agent nenajde relevantní informace ve svých připojených zdrojích, explicitně řekne „nemám o tom informace”, místo aby si vymýšlel
  • Ověřitelné odpovědi — uživatelé mohou kliknout na jakoukoli citaci a vidět původní zdrojový materiál. Tohle buduje důvěru a zjednodušuje ověření odpovědí agenta
  • Transparentnost confidence — confidence skóre pro každou citaci je viditelné, takže uživatelé vědí, jak silně zdroj podporuje tvrzení

Tohle ukotvující chování se vynucuje na systémové úrovni, ne jen přes system prompt. I kdyby system prompt nezmiňoval citace, agent framework automaticky připojí informace o zdroji ke každé odpovědi. Citace lze zakázat pro konkrétní use cases, ale defaultně jsou zapnuté.

Best practices

Po stavbě desítek produkčních agentů s našimi prvními zákazníky tady jsou vzorce, které konzistentně produkují nejlepší výsledky:

Návrh system promptu

  • Buďte specifičtí o roli agenta — „You are a support agent for ACME Corp’s billing system” je lepší než „You are a helpful assistant”
  • Definujte hranice — řekněte agentovi, jaká témata jsou mimo scope. „Do not answer questions about competitor products” zabrání off-topic odpovědím
  • Nastavte tón — „Respond in a professional but friendly tone. Use simple language. Avoid jargon unless the user uses it first”
  • Zahrňte ukázkové interakce — dvě nebo tři ukázky ideálních dvojic otázka-odpověď dramaticky zlepšují konzistenci

Kvalita dat

  • Udržujte zdroje aktuální — nastavte automatický sync pro datové zdroje, které se často mění. Zastaralá data vedou ke špatným odpovědím
  • Odstraňte duplicity — pokud stejná informace existuje ve třech dokumentech, agent může citovat všechny tři, což je hlučné. Konsolidujte, kde to jde
  • Používejte jasné názvy dokumentů — agent používá názvy dokumentů v citacích. „Q3-2026-Revenue-Report.pdf” je užitečnější než „report_final_v3.pdf”

Testování a monitoring

  • Vytvořte testovací sadu — udržujte seznam 20-50 otázek s očekávanými odpověďmi. Spouštějte je po každé aktualizaci dat nebo změně konfigurace
  • Monitorujte míru citací — pokud procento odpovědí s citacemi klesá, obvykle to znamená, že agent dostává otázky mimo svůj knowledge scope
  • Revidujte low-confidence odpovědi — nastavte alerty na odpovědi, kde všechny citace mají confidence pod 0,7. Tohle jsou kandidáti na přidání dalšího zdrojového materiálu

Připraveni postavit prvního agenta? Zaregistrujte se na app.stellarbase.ai a postupujte tímhle návodem krok za krokem — free tier obsahuje vše, co potřebujete pro start.