Kyra

A standalone AI agent platform with multi-LLM support, real-time dashboard, Python SDK, and CLI.

flowchart LR
    subgraph Clients["🖥️ Clients"]
        direction TB
        Dashboard["Dashboard<br/>Next.js"]
        SDK["Python SDK"]
        CLI["CLI"]
    end

    subgraph Core["⚡ Kyra Core"]
        direction TB
        API["FastAPI Server"]
        
        subgraph Services["Services"]
            LLM["LLM Service<br/>100+ models"]
            Runner["Agent Runner"]
            Executor["Task Executor"]
        end
        
        subgraph Tools["Built-in Tools"]
            T1["📂 File Ops"]
            T2["🔍 Web Search"]
            T3["💻 Code Exec"]
        end
    end

    subgraph Agents["🤖 AI Agents"]
        A1["Researcher"]
        A2["Coder"]
        A3["Writer"]
        A4["Analyst"]
    end

    subgraph Storage["💾 Storage"]
        DB[("SQLite")]
        WS["Workspace<br/>Files"]
    end

    Clients -->|"REST / WebSocket"| API
    API --> Services
    Services --> Tools
    Runner --> Agents
    Services --> Storage

    style Clients fill:#dbeafe,stroke:#2563eb
    style Core fill:#fef9c3,stroke:#ca8a04
    style Services fill:#fff7ed,stroke:#ea580c
    style Tools fill:#f0fdf4,stroke:#16a34a
    style Agents fill:#fdf4ff,stroke:#a855f7
    style Storage fill:#f1f5f9,stroke:#64748b

Features

• Multi-LLM Support: OpenAI, Anthropic, Ollama, and 100+ providers via LiteLLM
• MCP Server Support: Connect to external MCP servers for unlimited tool extensibility
• Real-time Dashboard: Next.js dashboard with live task updates
• Python SDK: Simple, intuitive API for programmatic access
• CLI Tool: Full-featured command-line interface
• Background Execution: Tasks run in background threads
• Built-in Tools: Web search, file operations, code execution

Quick Start

Installation

# Install the package
pip install -e .

# Set your LLM API key (recommended: OpenRouter for access to all models)
export KYRA_OPENROUTER_API_KEY=sk-or-v1-...

# Or use direct provider keys
export KYRA_OPENAI_API_KEY=sk-...
export KYRA_ANTHROPIC_API_KEY=sk-ant-...

# Or for local LLMs
export KYRA_OLLAMA_BASE_URL=http://localhost:11434

Start the Server

# Start API server + Dashboard (opens browser automatically)
kyra server start

# Or start without dashboard
kyra server start --no-dashboard

# Custom ports
kyra server start --port 9000 --dashboard-port 3001

Using the CLI

# Check available models and providers
kyra models                    # List available models
kyra providers                 # Show provider status
kyra test-model openai/gpt-5.4   # Test a specific model

# Create an network (workspace)
kyra network create "My Workspace"

# Create an agent
kyra agent create --name "Research Assistant" --network <network_id> --model openrouter/openai/gpt-5.4

# Run a task
kyra task create "Research the latest AI trends" --network <network_id> --wait

# Task management
kyra task list                           # List all tasks
kyra task status <task_id>               # Check task status  
kyra task decompose <task_id>            # Break into subtasks
kyra task run-all <task_id>              # Run all subtasks
kyra task continue <task_id> "more info" # Continue a task

# Deploy agents on-chain (ERC-8004)
# Prereqs (set once in .env)
export KYRA_private_key=0xabc...         # or PRIVATE_KEY
export KYRA_ETH_SEPOLIA_RPC=https://sepolia.rpc.provider
export KYRA_BASE_SEPOLIA_RPC=https://base-sepolia.rpc.provider
export KYRA_IPFS_API_TOKEN=pinata_jwt            # Pinata JWT for uploads

# Deploy an agent (uploads metadata to IPFS via Pinata, then calls IdentityRegistry.register)
# Deployment details are saved in the database. Re-deploying the same agent returns cached info.
kyra agent deploy <agent_id> --chain eth-sepolia
# Optional: re-use existing metadata URI
kyra agent deploy <agent_id> --chain base-sepolia --metadata-uri https://gateway.pinata.cloud/ipfs/<cid>

# View agent deployment status
kyra agent get <agent_id>  # Shows on-chain ID, tx hash, chain, and metadata URI if deployed

# Workspace file management
kyra workspace tree                      # Show directory tree
kyra workspace browse src/               # Browse directory
kyra workspace cat README.md             # Read a file

Using the Python SDK

from kyra import KyraClient

# Connect to local server (supports context manager)
with KyraClient(base_url="http://localhost:8000") as client:
    # Check available models
    models = client.config.get_models()
    print(f"Available models: {len(models['models'])}")
    
    # Create an network
    network = client.networks.create(name="Research Lab")
    
    # Create an agent
    agent = client.agents.create(
        name="Research Assistant",
        network_id=network["id"],
        model="openrouter/openai/gpt-5.4",
        role="researcher"
    )
    
    # Run a task and wait for result
    task = client.tasks.create(
        network_id=network["id"],
        description="What are the key benefits of AI agents?"
    )
    result = client.tasks.wait(task["id"])
    print(result["result"]["output"])
    
    # Decompose complex tasks
    complex_task = client.tasks.create(
        network_id=network["id"],
        description="Build a web scraper",
        run_mode="decompose"
    )
    subtasks = client.tasks.get_subtasks(complex_task["id"])
    client.tasks.run_all_subtasks(complex_task["id"])
    
    # Browse workspace files
    files = client.workspace.browse(".")
    content = client.workspace.read_file("README.md")

Project Structure

kyra-network/
├── kyra/
│   ├── server/          # FastAPI backend
│   │   ├── models/      # SQLAlchemy models
│   │   ├── schemas/     # Pydantic schemas
│   │   ├── api/         # API routes
│   │   ├── services/    # LLM, task executor
│   │   └── tools/       # Built-in tools
│   ├── client/          # Python SDK
│   └── cli/             # CLI commands
├── dashboard/           # Next.js frontend
└── examples/            # Example scripts

CLI Reference

Command	Description
kyra server start	Start API server and dashboard
kyra health	Check API health
kyra models	List available LLM models
kyra providers	Show provider configuration status
kyra test-model <id>	Test if a model is accessible
kyra tools	List available agent tools
Network
kyra network create <name>	Create a new network
kyra network list	List all networks
kyra network get <id>	Get network details
kyra network delete <id>	Delete an network
Agent
kyra agent create	Create a new agent
kyra agent list	List all agents
kyra agent get <id>	Get agent details
kyra agent update <id>	Update an agent
kyra agent sleep <id>	Put agent offline
kyra agent wake <id>	Wake agent up
Task
kyra task create <desc>	Create and run a task
kyra task list	List tasks
kyra task get <id>	Get task details
kyra task status <id>	Check task status
kyra task decompose <id>	Break task into subtasks
kyra task subtasks <id>	List subtasks
kyra task run-all <id>	Run all subtasks
kyra task continue <id>	Continue a completed task
kyra task cancel <id>	Cancel a running task
kyra task review <id>	Request subtask review
Workspace
kyra workspace list	List task workspaces
kyra workspace browse <path>	Browse directory
kyra workspace cat <file>	Read file contents
kyra workspace write <file>	Write to a file
kyra workspace tree	Show directory tree
kyra workspace mkdir <path>	Create directory
kyra workspace rm <path>	Delete file/directory
Config
kyra config init	Initialize configuration
kyra config show	Show current config
kyra config set <key> <val>	Set a config value
kyra config server	Show server config
kyra config reload	Reload server config
MCP
kyra mcp list	List MCP servers
kyra mcp add	Add a new MCP server
kyra mcp remove <name>	Remove an MCP server
kyra mcp connect <name>	Connect to an MCP server
kyra mcp disconnect <name>	Disconnect from server
kyra mcp tools <name>	List tools from server
kyra mcp refresh <name>	Refresh server capabilities
kyra mcp info <name>	Show server details
kyra mcp enable <name>	Enable an MCP server
kyra mcp disable <name>	Disable an MCP server
kyra mcp catalog	Browse MCP server presets
kyra mcp categories	List preset categories
kyra mcp install <id>	Install preset from catalog
kyra mcp uninstall <id>	Uninstall a preset
kyra mcp preset-info <id>	Show preset details

SDK Reference

from kyra import KyraClient

client = KyraClient(base_url="http://localhost:8000")

# Resources available:
client.networks      # Network management
client.agents       # Agent management
client.tasks        # Task management
client.tools        # Tool listing
client.config       # Configuration & models
client.workspace    # File operations

Resource	Methods
networks	create(), get(), list(), delete()
agents	create(), get(), list(), update(), delete(), sleep(), wake()
tasks	create(), get(), list(), wait(), decompose(), get_subtasks(), run_all_subtasks(), execute_subtask(), continue_task(), cancel(), get_messages(), request_review()
tools	list()
config	get(), get_models(), get_all_models(), get_providers(), get_default_model(), test_model(), reload()
workspace	get_info(), list_task_workspaces(), browse(), read_file(), write_file(), delete_file(), create_directory(), delete_directory(), get_tree()
mcp	list(), get(), create(), update(), delete(), connect(), disconnect(), refresh(), get_tools(), call_tool(), get_resources(), read_resource(), get_prompts(), get_all_tools()

API Endpoints

Method	Endpoint	Description
GET	/api/v1/networks	List networks
POST	/api/v1/networks	Create network
GET	/api/v1/agents	List agents
POST	/api/v1/agents	Create agent
PUT	/api/v1/agents/{id}	Update agent
POST	/api/v1/agents/{id}/sleep	Set agent offline
POST	/api/v1/agents/{id}/wake	Set agent idle
GET	/api/v1/tasks	List tasks
POST	/api/v1/tasks	Create & run task
POST	/api/v1/tasks/{id}/decompose	Decompose into subtasks
POST	/api/v1/tasks/{id}/run-all	Run all subtasks
POST	/api/v1/tasks/{id}/continue	Continue task
POST	/api/v1/tasks/{id}/cancel	Cancel task
GET	/api/v1/tools	List tools
GET	/api/v1/config/models	List available models
GET	/api/v1/config/providers	List providers
POST	/api/v1/config/test-model	Test a model
GET	/api/v1/workspace/browse	Browse workspace
GET	/api/v1/workspace/file	Read file
POST	/api/v1/workspace/file	Write file
GET	/api/v1/mcp/	List MCP servers
POST	/api/v1/mcp/	Create MCP server
GET	/api/v1/mcp/{id}	Get MCP server
PUT	/api/v1/mcp/{id}	Update MCP server
DELETE	/api/v1/mcp/{id}	Delete MCP server
POST	/api/v1/mcp/{id}/connect	Connect to server
POST	/api/v1/mcp/{id}/disconnect	Disconnect from server
POST	/api/v1/mcp/{id}/refresh	Refresh capabilities
GET	/api/v1/mcp/{id}/tools	Get server tools
POST	/api/v1/mcp/{id}/tools/call	Call a tool
GET	/api/v1/mcp/tools/all	Get all MCP tools
WS	/ws	WebSocket for real-time updates

MCP Server Integration

Kyra supports the Model Context Protocol (MCP) for connecting to external tool servers. Browse 30+ pre-configured servers or add your own.

One-Click Install from Catalog

Kyra includes a curated catalog of popular MCP servers:

# Browse available presets
kyra mcp catalog

# View categories
kyra mcp categories

# Search for specific tools
kyra mcp catalog --search "github"

# Install a preset with one command
kyra mcp install mcp-github

# Get preset details
kyra mcp preset-info mcp-fetch

# Uninstall a preset
kyra mcp uninstall mcp-github

Popular Presets:

• Filesystem - File and directory operations
• GitHub - Repository, issues, and PR management
• PostgreSQL/SQLite - Database queries and management
• Brave Search / Google Search - Web search capabilities
• Puppeteer - Browser automation
• Memory - Persistent knowledge graph
• Slack/Notion/Linear - Productivity integrations

Adding Custom MCP Servers

# Add an SSE MCP server
kyra mcp add --name weather-api --type sse --url http://localhost:8001/sse

# Add a STDIO MCP server (local process)
kyra mcp add --name local-tools --type stdio --command python --args "-m,my_mcp_server"

# List MCP servers
kyra mcp list

# Connect to a server
kyra mcp connect weather-api

# View available tools
kyra mcp tools weather-api

# Refresh server capabilities
kyra mcp refresh weather-api

Using MCP in Python

from kyra import KyraClient

client = KyraClient()

# Install from catalog
presets = client.mcp.list_presets()
client.mcp.install_preset("mcp-fetch")

# Or add a custom server
server = client.mcp.create(
    name="my-tools",
    server_type="sse",
    url="http://localhost:8001/sse"
)

# Connect and get tools
client.mcp.connect(server["id"])
tools = client.mcp.get_all_tools()

# MCP tools are automatically available to agents!
# They're prefixed with: mcp_servername_toolname

MCP Features

• Curated Catalog: 30+ pre-configured MCP servers ready to install
• One-Click Install: Enable popular tools instantly from dashboard or CLI
• Auto-discovery: Tools, resources, and prompts are discovered automatically
• Agent Integration: MCP tools seamlessly integrate with Kyra agents
• Dashboard UI: Manage MCP servers from the web dashboard
• Multiple Transports: STDIO, SSE, HTTP, and WebSocket support

Configuration

Environment Variables

# LLM API Keys (use KYRA_ prefix)
KYRA_OPENROUTER_API_KEY=sk-or-v1-...  # Recommended: access all models
KYRA_OPENAI_API_KEY=sk-...             # Direct OpenAI access
KYRA_ANTHROPIC_API_KEY=sk-ant-...      # Direct Anthropic access
KYRA_OLLAMA_BASE_URL=http://localhost:11434

# Default model (used when no model specified)
KYRA_DEFAULT_MODEL=openrouter/openai/gpt-5.4

# Server Configuration
KYRA_HOST=0.0.0.0
KYRA_PORT=8000
KYRA_DEBUG=false
KYRA_DATABASE_URL=sqlite:///./kyra.db

# Dashboard
KYRA_DASHBOARD_PORT=3000
KYRA_AUTO_OPEN_BROWSER=true

CLI Configuration

# Initialize config
kyra config init

# Set values
kyra config set base_url http://localhost:8000

# Show current config
kyra config show

Development

Running in Development Mode

# Start with auto-reload
kyra server start --reload

# Or run components separately
uvicorn kyra.server.main:app --reload --port 8000
cd dashboard && npm run dev

Running Tests

pip install -e ".[dev]"
pytest

Documentation

📚 Comprehensive documentation is available in the docs/ folder:

Document	Description
Architecture	Technical architecture, components, and data flow
User Guide	How to use Kyra Network effectively