Skip to main content

🎯 Setting Up Your First Agent

This guide walks you through deploying your first conversational AI agent in STELLA.

Prerequisites​

Before deploying an agent, ensure:

  • STELLA is running ](../scripts/start-k8s.sh`)
  • You have an OpenAI API key
  • You can access the Frontend UI at http://localhost:5173

Step 1: Create an Environment Variable Template​

Environment variable templates store API keys and configuration that agents need. Templates are encrypted and securely injected into agent pods as Kubernetes secrets.

  1. Open the Frontend UI at http://localhost:5173
  2. Go to Settings in the sidebar
  3. Click "New Template" in the Environment Variables section
  4. Add your OPENAI_API_KEY (required) and any optional keys (e.g., ELEVENLABS_API_KEY)
  5. Give the template a name (e.g., "Production Keys") and save
Agent Environment Variables

Learn how environment variables are securely injected into agent pods and which variables are required.

Step 2: Deploy an Agent​

  1. Create or open a session from the Sessions page
  2. Click "Deploy Agent" in the session view
  3. Select your environment variable template from the dropdown
  4. Choose an agent type:
    • stella-agent - Full-featured agent with advanced capabilities
    • stella-light-agent - Lightweight agent for simpler use cases
    • echo-agent - Simple test agent that echoes back messages
  5. Optionally select a Plan Template to define the conversation flow
  6. Click Deploy

The agent will start in a Kubernetes pod and automatically connect to the LiveKit room.

Step 3: Interact with Your Agent​

Once deployed, you can:

  • Voice: Click the microphone button to speak with the agent
  • Text: Type messages in the chat input
  • View transcripts: See real-time transcription of the conversation

Step 4: Monitor Your Agent​

  • View agent status in the session panel (Running, Starting, Stopped)
  • Click on the agent to see logs and metrics
  • Stop the agent when done to free up resources

Using the API​

You can also deploy agents programmatically via the API:

Create a Session​

curl -X POST http://localhost:3000/projects/{projectId}/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Session"}'

Start an Agent​

curl -X POST http://localhost:3000/sessions/{sessionId}/agents \
  -H "Content-Type: application/json" \
  -d '{
    "role": "conversational-ai",
    "planId": "cognitive_stimulation_demo_sm"
  }'

Get Agent Status​

curl http://localhost:3000/agents/{agentId}

View Agent Logs​

curl http://localhost:3000/agents/{agentId}/logs

Stop Agent​

curl -X DELETE http://localhost:3000/agents/{agentId}

Viewing Kubernetes Resources​

# View agent pods
kubectl get pods -n ai-agents -l app=conversational-ai-agent

# View specific agent logs
kubectl logs -n ai-agents <agent-pod-name>

# Describe pod for detailed events
kubectl describe pod -n ai-agents <agent-pod-name>

Troubleshooting​

Agent Won't Start​

  1. Check the agent image exists:

    docker images | grep stella

  2. View pod events:

    kubectl describe pod <agent-pod-name> -n ai-agents

  3. Check environment template has all required variables

Agent Disconnects Immediately​

  1. Verify LiveKit connection:

    curl http://localhost:7880

  2. Check agent logs for errors:

    kubectl logs <agent-pod-name> -n ai-agents

No Audio from Agent​

  1. Ensure microphone permissions are granted in browser
  2. Check TTS service is running: 
    kubectl get pods -n ai-agents | grep tts

Next Steps​