supyagent 0.1.0

LLM agents powered by supypowers - build AI agents with tool use, multi-agent orchestration, and secure credential management

Supyagent

LLM agents powered by supypowers tools.

Features

• 🤖 Interactive & Execution Agents - Chat interactively or run automated pipelines
• 🔧 Tool Integration - Use any supypowers function as an agent tool
• 🌐 Any LLM Provider - Via LiteLLM (OpenAI, Anthropic, Ollama, etc.)
• 📝 YAML Configuration - Simple, declarative agent definitions
• 🔄 Session Persistence - Conversations persist across sessions
• 🔐 Credential Management - Secure storage for API keys and secrets
• 🎭 Multi-Agent Orchestration - Agents can delegate tasks to other agents
• 📦 Batch Processing - Process multiple inputs from JSONL/CSV files

Installation

pip install supyagent

Or with uv:

uv pip install supyagent

Quick Start

# Create your first agent
supyagent new myagent

# Start chatting
supyagent chat myagent

Usage

Interactive Mode

# Create an interactive agent
supyagent new researcher

# Chat with it
supyagent chat researcher

# Resume a previous session
supyagent chat researcher --session <session-id>

# Start fresh
supyagent chat researcher --new

Execution Mode

For automation and pipelines:

# Create an execution agent
supyagent new summarizer --type execution

# Run with inline input
supyagent run summarizer "Summarize this text..."

# Run with file input
supyagent run summarizer --input document.txt

# Get JSON output
supyagent run summarizer --input doc.txt --output json

# Pipe from stdin
cat article.txt | supyagent run summarizer

Batch Processing

# Process multiple inputs
supyagent batch summarizer inputs.jsonl --output results.jsonl

# From CSV
supyagent batch summarizer data.csv --format csv

Multi-Agent Orchestration

# Use the planning agent to orchestrate complex tasks
supyagent plan "Build a Python library for data validation"

# The planner will delegate to specialist agents (coder, writer, researcher)

Agent Configuration

Agents are defined in YAML files in the agents/ directory:

name: researcher
description: An AI research assistant
type: interactive  # or "execution"

model:
  provider: anthropic/claude-3-5-sonnet-20241022
  temperature: 0.7
  max_tokens: 4096

system_prompt: |
  You are a helpful research assistant...

tools:
  allow:
    - "*"           # Allow all tools
    # or be specific:
    # - "web:*"     # All functions in web.py
    # - "math:calc" # Specific function
  deny:
    - "dangerous:*" # Block specific tools

# For multi-agent support
delegates:
  - coder
  - writer

LLM Providers

Supyagent uses LiteLLM, supporting 100+ providers:

model:
  # OpenAI
  provider: openai/gpt-4o
  
  # Anthropic
  provider: anthropic/claude-3-5-sonnet-20241022
  
  # Ollama (local)
  provider: ollama/llama3
  
  # Azure OpenAI
  provider: azure/gpt-4
  
  # Google
  provider: gemini/gemini-pro

Set API keys as environment variables:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

CLI Reference

Core Commands

Command	Description
supyagent new <name>	Create a new agent
supyagent list	List all agents
supyagent show <name>	Show agent details
supyagent chat <name>	Interactive chat session
supyagent run <name> <task>	Execute agent (non-interactive)
supyagent batch <name> <file>	Process multiple inputs
supyagent plan <task>	Run task through planning agent

Session Commands

Command	Description
supyagent sessions <name>	List sessions for an agent
supyagent chat <name> --session <id>	Resume a session
supyagent chat <name> --new	Start a new session

Agent Management

Command	Description
supyagent agents	List active agent instances
supyagent cleanup	Remove completed instances

In-Chat Commands

While chatting, use these commands:

Command	Description
/help	Show available commands
/tools	List available tools
/history	Show conversation history
/sessions	List your sessions
/switch <id>	Switch to another session
/new	Start a new session
/save <title>	Save session with title
/export <file>	Export session to file
/model <name>	Switch LLM model
/creds	Manage stored credentials
/clear	Clear conversation history
/quit	Exit the chat

Project Structure

your-project/
├── agents/              # Agent YAML definitions
│   ├── assistant.yaml
│   ├── planner.yaml
│   └── researcher.yaml
├── supypowers/          # Tool definitions (Python)
│   ├── hello.py
│   └── web_search.py
└── .supyagent/          # Runtime data (gitignore this)
    ├── sessions/        # Conversation history
    ├── credentials/     # Encrypted secrets
    └── registry.json    # Agent instances

Credential Management

Supyagent securely manages API keys and secrets:

# In chat, agents can request credentials
🔑 Credential requested: SLACK_API_TOKEN
   Purpose: To send messages to Slack
Enter value (or press Enter to skip): ****
Save for future sessions? [Y/n]: y

# View stored credentials
/creds

Credentials are encrypted at rest using Fernet encryption.

Multi-Agent Architecture

Create orchestrator agents that delegate to specialists:

# agents/planner.yaml
name: planner
type: interactive

delegates:
  - researcher  # Can delegate research tasks
  - coder       # Can delegate coding tasks
  - writer      # Can delegate writing tasks

system_prompt: |
  You are a planning agent. Break down complex tasks
  and delegate to specialist agents...

The planner can then:

1. Analyze tasks
2. Create execution plans
3. Delegate subtasks to appropriate agents
4. Synthesize results

Development

# Clone the repo
git clone https://github.com/ergodic-ai/supyagent
cd supyagent

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .

License

MIT

Related Projects

• supypowers - Tool execution framework
• LiteLLM - LLM provider abstraction