SmythOS SDK Practice

Learn to build AI Agents with SmythOS SDK through hands-on examples

Quick Start • Examples • Features • Structure • Setup

Overview

This is an interactive learning project for the SmythOS SDK - a powerful toolkit for building AI agents. The project provides 6 progressively complex examples, from basic chat to advanced planner-coder workflows.

Each example is a fully working Next.js application with:

Modern, dark-themed UI
Real-time streaming responses
Interactive chat interface
Source code you can study and modify

Quick Start

Prerequisites

Node.js 20.9.0 or higher
Bun (recommended) or pnpm/npm/yarn
API Keys for LLM providers (OpenAI, Anthropic, Groq, etc.)

Installation

# 1. Clone the repository
git clone https://github.com/smythos/sdk-agent.git
cd sdk-agent

# 2. Install dependencies
bun install

# 3. Set up environment variables
cp .env.example .env.local
# Edit .env.local and add your API keys

# 4. Start the development server
bun dev

Open in Browser

http://localhost:3000          # Home page
http://localhost:3000/practice # All practice examples

Practice Examples

Learning Path (Beginner to Advanced)

#	Example	Complexity	Description	Key Concepts
01	Basic Chat	⭐	Simple chat with crypto price skill	Agent creation, Skills, `agent.chat()`
02	Streaming Chat	⭐⭐	Real-time streaming responses	SSE, Event handlers, `TLLMEvent`
03	Persistent Chat	⭐⭐⭐	Chat history that persists	Session management, Multiple skills
04	Local Model	⭐⭐⭐	Use Ollama/LMStudio models	`Model.Local()`, Offline AI
05	Observability	⭐⭐⭐	OpenTelemetry tracing	Monitoring, Debugging, Metrics
06	Planner Coder	⭐⭐⭐⭐⭐	AI that plans and executes tasks	Multi-step workflows, Code generation

Example Details

01 - Basic Chat

const agent = new Agent({
  name: 'CryptoMarket Assistant',
  behavior: 'You are a crypto price tracker...',
  model: 'gpt-4o-mini',
});

agent.addSkill({
  name: 'Price',
  description: 'Get cryptocurrency price',
  process: async ({ coin_id }) => {
    // Fetch price from CoinGecko API
  },
});

const chat = agent.chat();
const response = await chat.prompt('What is the price of Bitcoin?');

02 - Streaming Chat

const streamResult = await chat.prompt('Tell me about Ethereum').stream();

streamResult.on(TLLMEvent.Content, (content) => {
  process.stdout.write(content); // Real-time output
});

streamResult.on(TLLMEvent.ToolCall, (toolCall) => {
  console.log('Tool called:', toolCall.name);
});

streamResult.on(TLLMEvent.End, () => {
  console.log('Stream complete');
});

03 - Persistent Chat

const agent = new Agent({
  id: 'crypto-assistant',  // Required for persistence
  name: 'CryptoMarket Assistant',
  model: 'gpt-4o-mini',
});

// Create persistent chat session
const chat = agent.chat({
  id: 'user-session-123',
  persist: true,  // Enable persistence
});

04 - Local Model

import { Model } from '@smythos/sdk';

const agent = new Agent({
  name: 'Local Assistant',
  model: Model.Local('llama3.2'),  // Uses Ollama
  // or: Model.Local('your-model', { baseUrl: 'http://localhost:1234/v1' })
});

05 - Observability

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-app');
const span = tracer.startSpan('chat-request');

// All agent operations are automatically traced
const response = await chat.prompt('Hello');

span.end();

06 - Planner Coder

const agent = new Agent({
  name: 'Planner Coder',
  behavior: 'You plan and execute coding tasks...',
  planner: true,  // Enable planner mode
});

agent.addSkill({ name: 'WriteFile', ... });
agent.addSkill({ name: 'ReadFile', ... });
agent.addSkill({ name: 'ExecuteCode', ... });

// Agent automatically breaks down complex tasks
const response = await chat.prompt('Create a REST API for user management');

Features

SDK Features Demonstrated

Agent Creation - Configure name, behavior, and model
Skills - Add custom capabilities to agents
Streaming - Real-time token-by-token responses
Persistence - Save and restore chat sessions
Local Models - Use Ollama, LMStudio, or any OpenAI-compatible endpoint
Observability - OpenTelemetry integration for monitoring
Planner Mode - Multi-step task decomposition and execution

Tech Stack

Technology	Purpose
Next.js 16	React framework with App Router
TypeScript	Type safety
Tailwind CSS 4	Styling
SmythOS SDK	AI agent development
Server-Sent Events	Real-time streaming

Environment Setup

Step 1: Create `.env.local`

cp .env.example .env.local

Step 2: Add API Keys

# Required: At least one LLM provider
OPENAI_API_KEY=sk-proj-xxx...
ANTHROPIC_API_KEY=sk-ant-xxx...
GROQ_API_KEY=gsk_xxx...

# Optional: Additional providers
GOOGLE_AI_API_KEY=
TOGETHER_API_KEY=
XAI_API_KEY=
DEEPSEEK_API_KEY=
TAVILY_API_KEY=
SCRAPFLY_API_KEY=

Step 3: Vault Configuration

The .smyth/vault.json file uses environment variable references:

{
  "default": {
    "openai": "$env(OPENAI_API_KEY)",
    "anthropic": "$env(ANTHROPIC_API_KEY)",
    "groq": "$env(GROQ_API_KEY)"
  }
}

The SDK automatically resolves $env(VARIABLE_NAME) at runtime.

Getting API Keys

Provider	Free Tier	Get Key
OpenAI	No	platform.openai.com
Anthropic	No	console.anthropic.com
Groq	Yes	console.groq.com
Google AI	Yes	aistudio.google.com

Project Structure

sdk-agent/
├── .smyth/
│   └── vault.json              # API keys vault (uses env vars)
├── src/
│   ├── app/
│   │   ├── page.tsx            # Home page
│   │   ├── practice/
│   │   │   ├── page.tsx        # Practice examples index
│   │   │   ├── 01-basic-chat/
│   │   │   │   └── page.tsx    # Basic chat UI
│   │   │   ├── 02-streaming-chat/
│   │   │   │   └── page.tsx    # Streaming chat UI
│   │   │   ├── 03-persistent-chat/
│   │   │   │   └── page.tsx    # Persistent chat UI
│   │   │   ├── 04-local-model/
│   │   │   │   └── page.tsx    # Local model UI
│   │   │   ├── 05-observability/
│   │   │   │   └── page.tsx    # Observability UI
│   │   │   └── 06-planner-chat/
│   │   │       └── page.tsx    # Planner coder UI
│   │   └── api/
│   │       └── practice/
│   │           ├── 01-basic-chat/
│   │           │   └── route.ts    # Basic chat API
│   │           ├── 02-streaming-chat/
│   │           │   └── route.ts    # Streaming API (SSE)
│   │           ├── 03-persistent-chat/
│   │           │   └── route.ts    # Persistent API
│   │           ├── 04-local-model/
│   │           │   └── route.ts    # Local model API
│   │           ├── 05-observability/
│   │           │   └── route.ts    # Observability API
│   │           └── 06-planner-chat/
│   │               └── route.ts    # Planner API
│   ├── components/             # Shared components
│   ├── lib/                    # Utilities and data
│   └── styles/                 # Global styles
├── .env.local                  # Environment variables (create this)
├── .env.example                # Example env file
└── package.json

Available Scripts

# Development
bun dev              # Start dev server with Turbopack
bun run build        # Production build
bun start            # Start production server

# Code Quality
bun run lint         # Run ESLint
bun run lint:fix     # Fix ESLint errors
bun run format       # Format with Prettier
bun run format:check # Check formatting

# Maintenance
bun run clear-cache  # Clear Next.js cache and reinstall

Local Model Setup (Example 04)

To use the Local Model example, you need a local LLM server:

Option 1: Ollama (Recommended)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2

# Start Ollama (runs on port 11434)
ollama serve

Option 2: LM Studio

Download from lmstudio.ai
Load any model
Start the local server (default: http://localhost:1234/v1)

Troubleshooting

Common Issues

"Rate limit exceeded"

Solution: Use a smaller model like gpt-4o-mini or switch to Groq (free tier)

"API key not found"

Solution: Check .env.local has correct keys and restart dev server

"Cannot connect to local model"

Solution: Ensure Ollama/LMStudio is running and accessible

"Module not found: styled-jsx"

Solution: Remove any <style jsx> blocks; use Tailwind CSS instead

"OS file watch limit reached" (Linux)

# Temporary fix
sudo sysctl fs.inotify.max_user_watches=524288

# Permanent fix
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Learn More

SmythOS Resources

Technologies Used

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by the SmythOS Team

Name		Name	Last commit message	Last commit date
.github		.github
.smyth		.smyth
.vscode		.vscode
src		src
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

SmythOS SDK Practice

Overview

Quick Start

Prerequisites

Installation

Open in Browser

Practice Examples

Learning Path (Beginner to Advanced)

Example Details

01 - Basic Chat

02 - Streaming Chat

03 - Persistent Chat

04 - Local Model

05 - Observability

06 - Planner Coder

Features

SDK Features Demonstrated

Tech Stack

Environment Setup

Step 1: Create .env.local

Step 2: Add API Keys

Step 3: Vault Configuration

Getting API Keys

Project Structure

Available Scripts

Local Model Setup (Example 04)

Option 1: Ollama (Recommended)

Option 2: LM Studio

Troubleshooting

Common Issues

"Rate limit exceeded"

"API key not found"

"Cannot connect to local model"

"Module not found: styled-jsx"

"OS file watch limit reached" (Linux)

Learn More

SmythOS Resources

Technologies Used

Contributing

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Step 1: Create `.env.local`