FivcPlayground

An intelligent agent ecosystem built on Strands for autonomous tool generation, task assessment, and dynamic agent orchestration.

🔄 Dual Backend Support: FivcPlayground supports both Strands (default) and LangChain backends. See Backend Selection Guide for details on switching backends.

🎯 Overview

FivcPlayground provides a flexible multi-agent system that can:

• Assess tasks intelligently to determine the best approach
• Retrieve and use tools dynamically based on task requirements
• Plan and execute complex workflows with specialized agents
• Generate and optimize tools autonomously

🚀 Quickstart

Prerequisites

• Python 3.10 or higher
• API keys for LLM providers (OpenAI, Ollama, etc.)

Installation

# Install with uv (recommended)
make install        # runtime + dev dependencies

# Or minimal installation
make install-min    # runtime only

# Or with pip
pip install -e .

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Configure your LLM provider settings in .env:

# OpenAI
OPENAI_API_KEY=your_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

# Or Ollama
OLLAMA_BASE_URL=http://localhost:11434

Quick Start

# Run an agent from CLI
uv run fivcplayground run Generic --query "What is machine learning?"

# Show available commands
uv run fivcplayground --help

📁 Project Structure

src/fivcplayground/
├── agents/          # Agent creation and management
│   └── types/       # Agent retriever and creator types
├── backends/        # Backend implementations (langchain, strands)
│   ├── langchain/   # LangChain backend
│   └── strands/     # Strands backend
├── embeddings/      # Vector database and embeddings
│   └── types/       # Embedding database types
├── models/          # LLM model factories and providers
│   └── types/       # Model types and implementations
│       ├── repositories/  # Model configuration repositories
│       └── base.py        # ModelConfig data model
├── schemas.py       # Pydantic data schemas
├── settings/        # Configuration management
├── tasks.py         # Task execution functions
├── tools/           # Tool management and retrieval
│   └── types/       # Tool retriever and config types
└── utils/           # Utility functions

configs/             # Configuration examples
examples/            # Usage examples
├── agents/          # Agent usage examples
└── tools/           # Tool usage examples
tests/               # Test suite
docs/                # Documentation

💻 Usage

Command Line Interface

# Show all available commands
fivcplayground --help

# Run an agent interactively
fivcplayground run Generic

# Run an agent with a specific query
fivcplayground run Generic --query "What is machine learning?"

# Run different agent types
fivcplayground run Companion --query "Tell me a joke"
fivcplayground run Consultant --query "How should I approach this task?"

# Clean temporary files
fivcplayground clean

# Show system information
fivcplayground info

Available Agents

• Generic - Standard agent for general task execution
• Companion - Friendly chat agent for conversations
• Consultant - Assesses tasks and recommends approaches
• Planner - Creates execution plans and teams
• Researcher - Analyzes patterns and workflows
• Engineer - Develops and optimizes tools
• Evaluator - Assesses performance and quality

Stream Agent Events

stream_async() is the primary execution path. It yields (event, run) pairs while the agent executes, and each run is an independent deep snapshot:

from fivcplayground.agents import AgentRunEvent

async for event, run in agent.stream_async(
    query="What is machine learning?",
    agent_run_repository=agent_run_repository,
    agent_run_session_id=session_id,
):
    if event is AgentRunEvent.STREAM:
        print(run.delta.text, end="", flush=True)
    elif event is AgentRunEvent.FINISH:
        print(f"\nfinished: {run.status}")

Events arrive as START, zero or more STREAM/TOOL/UPDATE events, and finally FINISH. Runtime failures are reported on the FINISH snapshot before the original exception is re-raised. Closing or cancelling the stream before completion persists a FAILED run. run_async() is a small reduction wrapper that consumes the stream and returns the final BaseModel or AgentRunContent; its optional event_callback observes the stream while reduction is in progress.

🧰 Available Tools

FivcPlayground includes built-in tools and supports MCP (Model Context Protocol) tools:

Built-in Tools:

• calculator - Mathematical calculations
• current_time - Current date and time
• python_repl - Python code execution

MCP Tools: Configure MCP servers in configs/mcp.yaml to add additional tools dynamically.

📚 Documentation

For comprehensive documentation, see the docs/ directory:

• System Design - Architecture and design principles
• Backend Selection Guide - Switching between Strands and LangChain backends
• Dependencies - Installation and dependency management
• Quick Start - Getting started with FivcPlayground
• Documentation Index - Complete documentation overview

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

MIT