Tutorial Mar 20, 2026 7 min read

Building Your First AI Agent with StellarBase

A step-by-step guide from zero to a production AI agent grounded in your data. Complete with citations, workflows, and access control.

What Are AI Agents?

An AI agent is more than a chatbot. While a chatbot responds to individual messages in isolation, an agent has access to tools, data sources, and workflows. It can retrieve information from your knowledge base, follow multi-step instructions, and take actions based on its reasoning.

In StellarBase, agents are the interface between your users and your data. They combine the conversational ability of large language models with the grounded knowledge from your document collections — powered by the DSM engine. Every answer is backed by real sources from your data, with citations that point to the exact document, page, and passage.

Here’s what makes StellarBase agents different from a basic “chat with your docs” setup:

DSM-powered retrieval — agents use the knowledge graph, not just vector search, to find relevant context. They follow relationships across documents to build complete answers
Mandatory citations — every factual claim links back to a source. If the agent can’t find a source, it says so instead of hallucinating
Access control — agents only see the data they’re authorized to access. Tag-based permissions ensure sensitive documents stay restricted
Workflow integration — agents can be embedded in automated workflows, triggered by webhooks, and chained with other agents

Step 1: Create Your Agent

Every agent starts with a configuration that defines its name, purpose, model, and behavior. You can create agents through the StellarBase UI or via the API. We’ll use the API here since it’s more explicit about what’s happening.

# 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
  }'

The API returns the agent ID, which you’ll use for all subsequent operations:

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

A few notes on the configuration:

model — any model available through StellarCloud, or a local model if you’re self-hosting. The agent will use this model for all reasoning and response generation
system_prompt — this is your agent’s personality and instructions. Be specific about what it should and shouldn’t do. Include instructions about citation behavior
temperature — lower values (0.1-0.3) produce more consistent, factual responses. Higher values (0.7-1.0) allow more creative answers. For knowledge agents, keep it low

Step 2: Connect Data Sources

An agent without data is just an LLM wrapper. The power of StellarBase agents comes from connecting them to your document collections. Collections can contain PDFs, Word documents, Markdown files, HTML pages, Confluence exports, or any text-based format.

# 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"
  }'

The search_mode parameter is important. Setting it to dsm enables the full Dynamic Semantic Module pipeline — entity recognition, relationship traversal, and graph-powered retrieval. This gives significantly better results than basic vector search, especially for questions that require information from multiple documents.

You can connect multiple collections to a single agent. For example, a support agent might have access to product documentation, FAQ articles, and release notes — each as a separate collection with different update schedules.

Step 3: Test Your Agent

With data connected, your agent is ready to answer questions. Send a test message to verify it’s working correctly:

# 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
  }'

The response includes the agent’s answer along with citations pointing to the exact sources:

{
	"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
}

Each citation includes the source document, location (page number or section), and a confidence score. The confidence score indicates how strongly the source supports the claim — scores above 0.8 are high confidence, 0.6-0.8 are moderate, and below 0.6 the agent will typically refrain from making the claim.

Testing Tips

Ask questions you know the answer to — verify the agent returns correct information with proper citations
Ask questions outside its knowledge — verify the agent admits when it doesn’t know something instead of hallucinating
Ask multi-hop questions — questions that require combining information from multiple documents. This is where DSM shines
Try adversarial prompts — ask the agent to ignore its instructions or make things up. Verify it stays grounded

Step 4: Configure Access Control

In production, you almost certainly want to restrict what data each agent can see. StellarBase uses tag-based access control — every document in a collection can have tags, and agents can be configured to only access documents with specific tags.

# 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"]
      }
    ]
  }'

This configuration ensures the support agent can only see documents tagged as “public” or “support” in the docs collection, and everything except “hr-only” documents in the knowledge base. If a user asks a question that could only be answered using a restricted document, the agent will respond as if that document doesn’t exist.

Access control is enforced at the retrieval level, not the response level. The restricted documents never reach the LLM context, which means there’s no risk of information leaking through prompt injection or other attacks.

Step 5: Add to Workflows

Agents become truly powerful when embedded in automated workflows. Instead of waiting for a human to send a message, the agent can be triggered automatically by events — a new support ticket, a document upload, a scheduled task.

# 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"
      }
    ]
  }'

This workflow triggers whenever a new support ticket arrives via webhook. The agent classifies the ticket, and based on the urgency level, either notifies the on-call team or adds it to the regular queue. No human intervention required for the triage step.

Workflows can chain multiple agents together. For example:

Agent 1 classifies the incoming request (support, sales, billing)
Agent 2 drafts a response using the relevant knowledge base
Agent 3 reviews the draft for accuracy and compliance
The final output goes to a human for approval before sending

Citations and Grounding

Grounding is what separates useful AI agents from unreliable ones. Every StellarBase agent response is grounded in your data, which means:

Every factual claim is cited — the agent attributes each piece of information to a specific source, with document name, location, and confidence
No hallucination by design — when the agent can’t find relevant information in its connected sources, it explicitly says “I don’t have information about this” instead of making something up
Verifiable answers — users can click on any citation to see the original source material. This builds trust and makes it easy to verify the agent’s responses
Confidence transparency — the confidence score for each citation is visible, so users know how strongly the source supports the claim

This grounding behavior is enforced at the system level, not just through the system prompt. Even if the system prompt doesn’t mention citations, the agent framework automatically attaches source information to every response. You can disable citations for specific use cases, but they’re on by default.

Best Practices

After building dozens of production agents with our early customers, here are the patterns that consistently produce the best results:

System Prompt Design

Be specific about the agent’s role — “You are a support agent for ACME Corp’s billing system” is better than “You are a helpful assistant”
Define boundaries — tell the agent what topics are out of scope. “Do not answer questions about competitor products” prevents off-topic responses
Set the tone — “Respond in a professional but friendly tone. Use simple language. Avoid jargon unless the user uses it first”
Include example interactions — two or three examples of ideal question-answer pairs dramatically improve consistency

Data Quality

Keep sources current — set up automatic sync for data sources that change frequently. Stale data leads to wrong answers
Remove duplicates — if the same information exists in three documents, the agent might cite all three, which is noisy. Consolidate where possible
Use clear document titles — the agent uses document titles in citations. “Q3-2026-Revenue-Report.pdf” is more useful than “report_final_v3.pdf”

Testing and Monitoring

Create a test suite — maintain a list of 20-50 questions with expected answers. Run them after every data update or configuration change
Monitor citation rates — if the percentage of responses with citations drops, it usually means the agent is getting questions outside its knowledge scope
Review low-confidence responses — set up alerts for responses where all citations have confidence below 0.7. These are candidates for adding more source material

Ready to build your first agent? Sign up at app.stellarbase.ai and follow this guide step by step — the free tier includes everything you need to get started.