wowbits-cli 0.1.0a4

WowBits AI Platform CLI - Manage connectors and integrations for AI workflows

WowBits Agents Guide

A comprehensive guide to creating, configuring, and running AI agents in the WowBits platform.

Table of Contents

• Overview
• Prerequisites
• Directory Structure
• Creating Agents
  • YAML Configuration Format
  • Tools
  • Skills
  • Agents
• Execution Modes
• Python Functions
• MCP Server Tools
• CLI Commands
• Examples
• Best Practices

---

Overview

WowBits agents are hierarchical AI systems built on Google's Agent Development Kit (ADK). An agent consists of:

• Agent: The root orchestrator with instructions and configuration
• Skills: Capabilities that an agent can use (can be nested)
• Tools: Python functions or MCP servers that skills can invoke

Agent
├── Skill A
│   ├── Tool 1 (Python Function)
│   └── Tool 2 (MCP Server)
└── Skill B
    ├── Skill B1 (nested skill)
    └── Tool 3

---

Prerequisites

1. Run Setup: Initialize the WowBits environment

   wowbits setup
   

2. Environment Variables: Ensure WOWBITS_ROOT_DIR is set (done automatically by setup)

3. Database: A running Supabase/PostgreSQL database with the schema created

---

Directory Structure

After setup, your WOWBITS_ROOT_DIR should have this structure:

~/wowbits/                    # WOWBITS_ROOT_DIR
├── .env                      # Environment variables (API keys, DB connection)
├── agent_studio/             # YAML configuration files for agents
│   └── my_agent.yaml
├── agent_runner/             # Generated agent code (auto-created)
│   └── my_agent/
│       └── agent.py
└── functions/                # Python function files
    ├── requirements.txt      # Dependencies for functions
    ├── search_web.py
    └── calculate.py

---

Creating Agents

YAML Configuration Format

Agent configurations are written in YAML with multiple documents separated by ---. The documents are processed in order: tools → skills → agents.

Each document must have:

• kind: The type (tool, skill, or agent)
• name: A unique identifier

Tools

Tools are the atomic capabilities that skills can use. WowBits supports two types:

Python Function Tools

---
kind: tool
name: search_tool
type: PYTHON_FUNCTION
python_function_name: search_web  # Name of function in WOWBITS_ROOT_DIR/functions/
description: Search the web for information

MCP Server Tools

---
kind: tool
name: neo4j_tool
type: MCP_SERVER
mcp_config_name: neo4j_server  # Name in mcp_configs table
description: Query Neo4j database

Skills

Skills define capabilities with instructions and can use tools or other skills.

---
kind: skill
name: research_skill
description: Research and gather information from various sources
instructions: |
  You are a research specialist. When asked to research a topic:
  1. Use the search tool to find relevant information
  2. Synthesize findings into a coherent summary
  3. Cite your sources
tools:
  - search_tool
config:
  exec_mode: llm           # llm, sequential, or parallel
  model: gpt-4.1           # or any LiteLLM-supported model
  temperature: 0.2
  max_output_tokens: 32000
  output_key: research_result  # Optional: store output in session state

Agents

Agents are the root-level orchestrators that combine skills.

---
kind: agent
name: research_assistant
description: An AI assistant that can research topics and answer questions
instructions: |
  You are a helpful research assistant. Use your skills to:
  - Research topics thoroughly
  - Provide accurate, well-sourced answers
  - Ask clarifying questions when needed
skills:
  - research_skill
  - summary_skill
status: ACTIVE  # ACTIVE, INACTIVE, or MAINTENANCE
config:
  exec_mode: llm
  model: gpt-4.1
  temperature: 0.3

---

Execution Modes

WowBits supports three execution modes for both agents and skills:

LLM Mode (Default)

The LLM decides when and how to use sub-skills/tools.

config:
  exec_mode: llm

Sequential Mode

Skills execute in a defined order, passing results to the next.

config:
  exec_mode: sequential
skills:
  - gather_data      # Runs first
  - analyze_data     # Runs second
  - generate_report  # Runs third

Parallel Mode

All sub-skills execute simultaneously.

config:
  exec_mode: parallel
skills:
  - search_google
  - search_arxiv
  - search_wikipedia

---

Python Functions

Creating a Function

1. Create a Python file in WOWBITS_ROOT_DIR/functions/:

# functions/search_web.py

def search_web(query: str, num_results: int = 5) -> dict:
    """
    Search the web for information.
    
    Args:
        query: The search query
        num_results: Number of results to return
        
    Returns:
        dict with search results
    """
    # Your implementation here
    import requests
    
    # Example using a search API
    response = requests.get(
        "https://api.search.com/search",
        params={"q": query, "limit": num_results}
    )
    return response.json()

2. Add dependencies to functions/requirements.txt:

requests>=2.31.0
beautifulsoup4>=4.12.0

3. Sync functions to the database:

wowbits create functions

Function Requirements

• Function name must match filename: search_web.py should contain def search_web(...)
• Use type hints: For proper tool schema generation
• Include docstrings: Description and args are extracted for the tool schema
• Return serializable data: Results must be JSON-serializable

---

MCP Server Tools

MCP (Model Context Protocol) servers provide tool capabilities over HTTP.

Setup MCP Config

First, create an MCP configuration in the database (via SQL or API):

INSERT INTO mcp_configs (name, url, config) VALUES (
  'neo4j_server',
  'http://localhost:8080',
  '{"transport_mode": "http"}'
);

Use in YAML

---
kind: tool
name: graph_query
type: MCP_SERVER
mcp_config_name: neo4j_server
description: Query the knowledge graph

Supported Transport Modes

• http: Streamable HTTP connection
• sse: Server-Sent Events connection

---

CLI Commands

Setup

# Initialize WowBits environment
wowbits setup

# Setup with custom root directory
wowbits setup --root-dir /path/to/wowbits

Functions

# List all registered functions
wowbits list functions

# Sync functions from WOWBITS_ROOT_DIR/functions/ to database
wowbits create functions

# Sync from custom directory
wowbits create functions --dir /path/to/functions

Agents

# Create agent from YAML (looks for WOWBITS_ROOT_DIR/agent_studio/<name>.yaml)
wowbits create agent my_agent

# Create agent from custom YAML path
wowbits create agent my_agent -c /path/to/config.yaml

# List all agents
wowbits list agents

# Run agent in web mode (starts ADK web server)
wowbits run agent my_agent

---

Examples

Example 1: Simple Research Agent

# agent_studio/research_agent.yaml

---
kind: tool
name: web_search
type: PYTHON_FUNCTION
python_function_name: search_web
description: Search the web for information

---
kind: skill
name: research
description: Research topics using web search
instructions: |
  You are a research specialist. When asked about a topic:
  1. Search for relevant information using the web_search tool
  2. Compile and summarize the findings
  3. Always cite your sources with URLs
tools:
  - web_search
config:
  model: gpt-4.1
  temperature: 0.2

---
kind: agent
name: research_agent
description: Research assistant that finds and summarizes information
instructions: |
  You are a helpful research assistant. Help users find information
  on any topic by using your research capabilities. Be thorough,
  accurate, and always provide sources.
skills:
  - research
status: ACTIVE
config:
  model: gpt-4.1
  temperature: 0.3

Example 2: Multi-Stage Pipeline Agent

# agent_studio/content_pipeline.yaml

---
kind: tool
name: scrape_url
type: PYTHON_FUNCTION
python_function_name: scrape_url
description: Scrape content from a URL

---
kind: skill
name: gather_content
description: Gather content from provided URLs
instructions: Use the scraper to extract content from each URL.
tools:
  - scrape_url
config:
  model: gpt-4.1
  output_key: raw_content

---
kind: skill
name: analyze_content
description: Analyze and categorize the gathered content
instructions: |
  Analyze the content in session state under 'raw_content'.
  Identify key themes, sentiment, and main points.
config:
  model: gpt-4.1
  output_key: analysis

---
kind: skill
name: generate_summary
description: Generate a final summary report
instructions: |
  Using the analysis from session state, create a comprehensive
  summary report with key findings and recommendations.
config:
  model: gpt-4.1

---
kind: agent
name: content_pipeline
description: Multi-stage content processing pipeline
instructions: Process and analyze content from multiple sources.
skills:
  - gather_content
  - analyze_content
  - generate_summary
config:
  exec_mode: sequential

Example 3: Parallel Search Agent

# agent_studio/multi_search.yaml

---
kind: tool
name: google_search
type: PYTHON_FUNCTION
python_function_name: google_search
description: Search Google

---
kind: tool
name: arxiv_search
type: PYTHON_FUNCTION
python_function_name: arxiv_search
description: Search ArXiv papers

---
kind: skill
name: search_google
description: Search Google for general information
instructions: Search Google and return top results.
tools:
  - google_search
config:
  output_key: google_results

---
kind: skill
name: search_arxiv
description: Search ArXiv for academic papers
instructions: Search ArXiv and return relevant papers.
tools:
  - arxiv_search
config:
  output_key: arxiv_results

---
kind: skill
name: parallel_search
description: Search multiple sources simultaneously
instructions: Coordinate parallel searches
skills:
  - search_google
  - search_arxiv
config:
  exec_mode: parallel

---
kind: skill
name: synthesize_results
description: Combine results from all searches
instructions: |
  Combine and deduplicate results from google_results and arxiv_results
  in session state. Rank by relevance.
config:
  model: gpt-4.1

---
kind: agent
name: multi_search_agent
description: Agent that searches multiple sources in parallel
instructions: Search across multiple sources and provide unified results.
skills:
  - parallel_search
  - synthesize_results
config:
  exec_mode: sequential

---

Best Practices

1. Structure Your YAML Properly

• Define tools first, then skills, then agents
• Use descriptive names that indicate purpose
• Keep instructions clear and actionable

2. Use Output Keys for Pipelines

When building sequential pipelines, use output_key to pass data between skills:

config:
  output_key: step1_result

3. Choose the Right Execution Mode

Mode	Use When
llm	Agent should decide dynamically which skills to use
sequential	Steps must happen in order (pipelines)
parallel	Multiple independent operations that can run simultaneously

4. Keep Functions Focused

• One function per file
• Single responsibility
• Clear input/output types
• Comprehensive error handling

5. Test Incrementally

1. Test functions independently first
2. Test skills with their tools
3. Test the full agent

6. Use Appropriate Models

• Use gpt-4.1 or similar for complex reasoning
• Use lighter models for simple tasks
• Adjust temperature based on task (lower for factual, higher for creative)

7. Document Your Agents

Include clear descriptions and instructions so the agent (and other developers) understand the purpose and expected behavior.

---

Troubleshooting

"Python function not found"

# Ensure functions are synced to database
wowbits create functions

"Agent not found"

# Check if agent was created
wowbits list agents

# Recreate from YAML
wowbits create agent my_agent

"WOWBITS_ROOT_DIR not set"

# Run setup again
wowbits setup

Cycle Detected in Skills

Skills cannot reference themselves directly or indirectly. Check your skills arrays for circular dependencies.

---

Additional Resources

• WowBits CLI README
• Database Schema
• Google ADK Documentation