Quick Start Guide - ZwartifyOS Agent Platform

🚀 Getting Started

Prerequisites

Node.js 18+ installed
Claude API key (from Anthropic)

Initial Setup

Clone the repository:

git ,[object Object], https://github.com/kriszwart/ZwartifyOSv1.git
,[object Object], ZwartifyOSv1

Install dependencies:
```
npm install
```
Configure API Key

Option A: Use Settings Page (Recommended for Web UI)
- Start the development server first (see step 4)
- Navigate to http://localhost:3000
- Go to /settings or click "Settings" in the navigation
- Enter your Anthropic API key
- Click "Save API Key"
- Your API key is stored securely in your browser (localStorage)
- Works immediately without restarting the server
Option B: Use Environment File
- Create .env.local file in the root directory:
```
CLAUDE_API_KEY=sk-ant-your-api-key-here
# OR
ANTHROPIC_API_KEY=sk-ant-your-api-key-here
```
- Restart the development server after creating/updating .env.local
Note: ZwartifyOS is open source. You bring your own API key. All API calls use your Anthropic API key, and you have full visibility into token usage and costs.
Start Development Server
```
npm run dev
```
Open in Browser Navigate to: http://localhost:3000

If using Settings page: Go to /settings to add your API key

🚀 Deploy to Vercel

Click the button above or import repository on Vercel
Add environment variables:
- CLAUDE_API_KEY (required)
- API_KEY (optional, for API authentication)
- RATE_LIMIT_ENABLED (optional, for rate limiting)
Deploy automatically on every push

🎯 Example Agents (Ready to Test!)

ZwartifyOS comes with 7 pre-built example agents with specialised skills:

📄 PDF Processor

Skill: PDF Processing
Best For: Office Workers, Accountants, Legal Professionals, Administrators
Use Cases: Document digitization, invoice processing, form automation, report generation
Test: Upload a PDF and ask "Summarize this document" or "Extract all text"
Location: /agents → Click "View" on "pdf-processor"

📊 Data Analyst

Skill: Data Analysis
Best For: Data Analysts, Business Analysts, Researchers, Product Managers
Use Cases: Sales reporting, customer behaviour analysis, performance metrics, A/B testing
Test: "Analyse this dataset and find trends" or "What are the key insights?"
Location: /agents → Click "View" on "data-analyst"

🔍 Code Reviewer

Skill: Code Review
Best For: Developers, Engineering Teams, Code Reviewers, Tech Leads
Use Cases: Pre-merge code reviews, security audits, code quality improvements, onboarding
Test: Paste code and ask "Review this code for security vulnerabilities"
Location: /agents → Click "View" on "code-reviewer"

✍️ Content Writer

Skill: Content Writing
Best For: Content Writers, Marketing Teams, Bloggers, Social Media Managers
Use Cases: Blog content creation, social media campaigns, email marketing, SEO optimization
Test: "Write a blog post about AI agents" or "Create social media content for product launch"
Location: /agents → Click "View" on "content-writer"

📧 Email Assistant

Skill: Email Management
Best For: Sales Teams, Customer Support, Executives, HR Teams
Use Cases: Customer communication, sales outreach, internal communications, template creation
Test: "Draft a professional follow-up email" or "Create an email template for customer support"
Location: /agents → Click "View" on "email-assistant"

🔬 Research Assistant

Skill: Research
Best For: Researchers, Analysts, Product Managers, Consultants, Students
Use Cases: Market research, competitive analysis, due diligence, trend analysis
Test: "Research competitors in the AI agent space" or "Analyse market trends for SaaS products"
Location: /agents → Click "View" on "research-assistant"

💬 Customer Support

Skills: PDF Processing + Email Management
Best For: Customer Support Teams, Help Desks, Service Teams
Use Cases: Customer communication, document analysis, troubleshooting, email templates
Test: Upload a customer document and ask "Help me understand this customer issue"
Location: /agents → Click "View" on "customer-support"

How to Test Example Agents

View All Agents:
- Go to /agents - you'll see all 7 example agents listed
- Each agent shows its assigned skills as badges
Test Individual Agent:
- Click "View" on any agent card
- You'll see the agent detail page with:
  - Agent info, prompt, and skills
  - Test interface to chat with the agent
  - PDF and image upload support
Test via Main Interface:
- Go to /agent (main test interface)
- Agents automatically detect relevant skills from your input
- Type questions like "Extract text from PDF" or "Analyse data"

📖 Your First Agent (5 Minutes)

Step 1: Create an Agent

Go to /agents or click "Agents" in the navigation
Click "+ Create Agent"
Fill in:
- Name: my-first-agent
- Description: A helpful assistant
- Prompt: You are a helpful AI assistant. Answer questions clearly and concisely.
- Enabled: ✓ (checked)
- Skills: (Optional) Select skills from the dropdown
Click "Create Agent"

Step 2: Test Your Agent

Go to /agent or click "Test" in navigation
Type: Tell me a joke about programming
Click Send
See your agent's response!

Step 3: View Execution Logs

Go back to /agents
Click "View" on your agent
See detailed execution logs including:
- Input/output
- Execution time
- Any tool calls
- Error details (if any)

🧠 Using RAG (Knowledge Base)

Step 1: Create a RAG Folder

Go to /rag
Click "+ Create Folder"
Name it: my-knowledge-base
Click "Create Folder"

Step 2: Upload Documents

Select your folder
Click "+ Upload File"
Choose a file (.txt, .md, .pdf, .html, .json, etc.)
File is automatically processed and chunked

Step 3: Use RAG with Agent

When creating/editing an agent, you can assign a RAG folder to automatically enhance its context.

🎯 Using Skills

View Available Skills

Go to /skills to see all available skills
Each skill shows:
- Target Audience: Who would benefit from this skill
- Use Cases: Real-world applications
- Industries: Where it's commonly used
Default skills include:
- PDF Processing - Extract text, tables, fill forms (Finance, Legal, Accounting)
- Data Analysis - Analyse datasets, create visualisations (E-commerce, Marketing, SaaS)
- Code Review - Review code for bugs, security, best practices (Software Development, FinTech)
- Content Writing - Create blogs, marketing copy, social media (Marketing, E-commerce, Media)
- Email Management - Draft emails, create templates (Sales, Customer Service, HR)
- Research - Conduct research, analyse information (Consulting, Research, Education)
- API Integration - Design and integrate APIs (FinTech, E-commerce, SaaS)

Assign Skills to Agents

When creating/editing an agent, scroll to "Skills" section
Select skills from the checklist
Agents automatically use assigned skills when relevant
Skills provide domain expertise and workflows to enhance agent capabilities

📊 Dashboard Overview

Visit /dashboard to see:

Total Executions: How many times agents have run
Success Rate: Percentage of successful executions
Agent Statistics: Number of agents and their status
Recent Executions: Latest agent runs

🚀 Next Steps

Test Example Agents - Try the 7 pre-built agents at /agents
Explore Skills - See available skills at /skills with use cases and target audiences
Create Your Own - Build custom agents with specific skills
Upload Documents - Use RAG for knowledge-based agents
View Logs - Monitor agent performance and execution history
Schedule Agents - Automate agent runs with cron schedules

🕐 Scheduling Agents

Create a Schedule

Use the API to create a schedule:

curl -X POST http://localhost:3000/api/schedules \
  -H ,[object Object], \
  -d ,[object Object],

Cron Expression Examples

0 9 * * * - Every day at 9 AM
0 */6 * * * - Every 6 hours
0 0 * * 1 - Every Monday at midnight
*/30 * * * * - Every 30 minutes

💾 Conversation Memory

Agents automatically maintain conversation history when:

useMemory option is enabled (default: true)
Agent has an agentId set

The agent will remember previous messages in the conversation and use them for context.

🔧 API Usage Examples

Create an Agent

curl -X POST http://localhost:3000/api/agents \
  -H ,[object Object], \
  -d ,[object Object],

Run an Agent

curl -X POST http://localhost:3000/api/agent \
  -H ,[object Object], \
  -d ,[object Object],

Get Agent Executions

curl http://localhost:3000/api/agents/{agent-id}/executions?,[object Object],=10

Upload File to RAG Folder

curl -X POST http://localhost:3000/api/rag/folders/{folder-id}/files \
  -F ,[object Object],

🎯 Common Use Cases

1. Customer Support Agent

Create agent with customer service prompt
Upload company FAQ documents to RAG folder
Agent can answer questions using company knowledge

2. Content Generator

Create agent with creative writing prompt
Schedule daily content generation
View generated content in execution logs

3. Data Analyst

Create agent with data analysis prompt
Upload datasets to RAG folder
Agent can analyse and report on data

4. Code Assistant

Create agent with programming expertise prompt
Use memory for context-aware code help
Agent remembers previous code discussions

🐛 Troubleshooting

Agent Not Responding

Check API Key Configuration:
- If using Settings page: Go to /settings and verify your API key is saved
- If using .env.local: Check the file exists and contains CLAUDE_API_KEY=sk-ant-...
- Restart dev server after changing .env.local
Check execution logs for error details
Verify your API key is valid at Anthropic Console

RAG Not Working

Ensure files are uploaded and processed
Check file format is supported
Verify folder is assigned to agent

Schedules Not Running

Ensure scheduler is started (check console logs)
Verify cron expression is valid
Check schedule is enabled

📚 Next Steps

Explore the Dashboard to see system statistics
Create multiple agents for different tasks
Set up RAG folders for domain-specific knowledge
Schedule agents for automated tasks
Review execution logs to optimise prompts

🔗 Useful Links

Settings: /settings - Configure your API key
Dashboard: /dashboard
Agents: /agents
Agent Testing: /agent
RAG Management: /rag
Agent Logs: /agents/[id]/logs

💡 Tips

Start Simple: Begin with basic prompts, then refine
Use RAG: Upload relevant documents for better context
Monitor Logs: Review execution logs to improve prompts
Enable Memory: Use conversation memory for better continuity
Test Often: Use the /agent page to test before deploying

Happy Building! 🎉