name: olakai-get-started
description: >
Get started with Olakai - install, authenticate, and set up your first agent.

AUTO-INVOKE when: CLI is not installed, user is not authenticated, user asks
about getting started with Olakai, user wants to try Olakai, user mentions
they don't have an account yet, or when other skills fail due to missing prerequisites.

TRIGGER KEYWORDS: get started, setup, install olakai, olakai account, sign up,
signup, new to olakai, try olakai, olakai onboarding, first agent, getting started,
no account, create account, register.

DO NOT load for: users who are already authenticated and have agents set up
(use olakai-create-agent, olakai-add-monitoring, or olakai-troubleshoot instead).
license: MIT
metadata:
author: olakai
version: "1.8.0"

Get Started with Olakai

This skill helps you get set up with Olakai from scratch - from creating an account to generating your first monitored event.

Quick Status Check

Before proceeding, let's check your current setup status.

Step 0: Detect Current State

Run these diagnostic commands to determine where to start:

# Check 1: Is CLI installed?
which olakai || echo "CLI_NOT_INSTALLED"

# Check 2: Is user authenticated?
olakai whoami 2>/dev/null || echo "NOT_AUTHENTICATED"

# Check 3: Are there any agents?
olakai agents list --json 2>/dev/null | head -5 || echo "NO_AGENTS_OR_NOT_AUTH"

Based on results, jump to the appropriate section:

Step 1: Create an Olakai Account

If you don't have an Olakai account yet, sign up at:

https://app.olakai.ai/signup

What you get:
- Free tier - Monitor up to 1,000 events/month
- Dashboard - Real-time visibility into AI usage
- KPIs - Track custom metrics across your agents
- Governance - Set policies and risk controls

After signing up, you'll have access to the dashboard where you can see your agents and events.

Step 2: Install the CLI

The Olakai CLI is the primary tool for configuring agents, KPIs, and custom data.

2.1 Install via npm

npm install -g olakai-cli

2.2 Verify Installation

olakai --version
# Should output: olakai-cli/0.1.x

2.3 Troubleshooting Installation

Permission errors on macOS/Linux:

# Option 1: Use sudo (not recommended)
sudo npm install -g olakai-cli

# Option 2: Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g olakai-cli

Windows:

# Run PowerShell as Administrator
npm install -g olakai-cli

Step 3: Authenticate

Connect the CLI to your Olakai account.

3.1 Login

olakai login

This opens your browser for secure authentication. After logging in:
- The CLI stores your session locally
- No API key needed for CLI operations
- Session persists until you explicitly logout

3.2 Verify Authentication

olakai whoami

Expected output:

Logged in as: [email protected]
Account: Your Organization

3.3 Troubleshooting Authentication

"Not authenticated" errors:

# Clear cached credentials and re-login
olakai logout
olakai login

Browser doesn't open:

# The CLI will display a URL - copy and paste it manually
olakai login
# Look for: "Open this URL in your browser: https://app.olakai.ai/..."

Corporate proxy/firewall issues:
- Ensure app.olakai.ai is accessible
- Check if your organization requires VPN

Step 4: Create Your First Agent

An "agent" in Olakai represents any AI-powered feature you want to monitor.

4.1 Create the Agent

# Create agent with an API key for SDK integration
olakai agents create \
  --name "My First Agent" \
  --description "Testing Olakai integration" \
  --with-api-key \
  --json

Save the output! It contains your apiKey which you'll need for SDK integration:

{
  "id": "cmkbteqn501kyjy4yu6p6xrrx",
  "name": "My First Agent",
  "apiKey": "sk_agent_xxxxx..."
}

4.2 Set the API Key as Environment Variable

# Add to your shell profile (.bashrc, .zshrc, etc.)
export OLAKAI_API_KEY="sk_agent_xxxxx..."

Or add to your project's .env file:

OLAKAI_API_KEY=sk_agent_xxxxx...

4.3 Retrieve API Key Later

If you need to get the API key again:

olakai agents get AGENT_ID --json | jq '.apiKey'

Step 5: Install the SDK

Choose based on your project's language.

TypeScript/JavaScript

npm install @olakai/sdk

Quick Integration:

import { OlakaiSDK } from "@olakai/sdk";
import OpenAI from "openai";

// Initialize Olakai
const olakai = new OlakaiSDK({
  apiKey: process.env.OLAKAI_API_KEY!
});
await olakai.init();

// Wrap your OpenAI client
const openai = olakai.wrap(
  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  { provider: "openai" }
);

// Use as normal - events are automatically tracked
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }]
});

Python

pip install olakai-sdk

Quick Integration:

import os
from openai import OpenAI
from olakaisdk import olakai_config, instrument_openai

# Initialize Olakai
olakai_config(os.getenv("OLAKAI_API_KEY"))
instrument_openai()

# Use OpenAI as normal - events are automatically tracked
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Step 6: Generate a Test Event

Let's verify everything is working.

6.1 Run Your Code

Execute the code from Step 5. This should:
1. Make an LLM call
2. Automatically send event data to Olakai

6.2 Fetch the Event

# List recent events (replace with your agent ID)
olakai activity list --limit 1 --json

6.3 Verify Event Details

# Get full event details
olakai activity get EVENT_ID --json | jq '{prompt, response, tokens, model}'

Expected output:

{
  "prompt": "Hello!",
  "response": "Hello! How can I assist you today?",
  "tokens": 25,
  "model": "gpt-4"
}

6.4 Check the Dashboard

Open https://app.olakai.ai and navigate to your agent's activity view. You should see the event appear within seconds.

Step 7: Next Steps

You're now set up! Here's what to explore next:

Add Custom Data to Events

Track business-specific metrics:

// TypeScript
const response = await openai.chat.completions.create(
  { model: "gpt-4", messages },
  {
    customData: {
      feature: "customer-support",
      ticketId: "TICKET-123",
      priority: 1
    }
  }
);

# Python
from olakaisdk import olakai_context

with olakai_context(customData={"feature": "customer-support", "ticketId": "TICKET-123"}):
    response = client.chat.completions.create(...)

Create KPIs

Define metrics that aggregate your custom data:

# First, create the custom data config for your agent
olakai custom-data create --agent-id YOUR_AGENT_ID --name "Priority" --type NUMBER

# Then create a KPI
olakai kpis create \
  --name "High Priority Events" \
  --agent-id YOUR_AGENT_ID \
  --calculator-id formula \
  --formula "IF(Priority == 1, 1, 0)" \
  --aggregation SUM

Note: KPIs are created per-agent. If you later create additional agents, you'll need to create KPIs for each one separately — they can't be shared across agents. CustomDataConfigs, on the other hand, are account-level and shared.

Learn More

• /olakai-create-agent - Detailed guide for building agents with full observability
• /olakai-add-monitoring - Add monitoring to existing AI code
• /olakai-troubleshoot - Debug issues with events or KPIs

Troubleshooting Quick Reference

CLI Issues

SDK Issues

Authentication Issues

Quick Reference

# Check status
which olakai              # CLI installed?
olakai whoami             # Authenticated?
olakai agents list        # Agents exist?

# Setup commands
npm install -g olakai-cli # Install CLI
olakai login              # Authenticate
olakai agents create --name "Name" --with-api-key --json  # Create agent

# SDK installation
npm install @olakai/sdk   # TypeScript
pip install olakai-sdk    # Python

# Verify events
olakai activity list --limit 1 --json
olakai activity get EVENT_ID --json

Summary Checklist

• [ ] Account created at https://app.olakai.ai/signup
• [ ] CLI installed (npm install -g olakai-cli)
• [ ] CLI authenticated (olakai login)
• [ ] First agent created with API key
• [ ] OLAKAI_API_KEY environment variable set
• [ ] SDK installed (@olakai/sdk or olakai-sdk)
• [ ] Test event generated and visible in dashboard

Once all boxes are checked, you're ready to build production AI agents with full observability!