Phero Project Homepage

Why Phero?

🎯 Purpose-built for agents: Not an LLM wrapper; a framework for orchestrating cooperative agent systems
🧩 Composable primitives: Small, focused packages that solve specific problems
🔧 Tool-first design: Built-in support for function tools, skills, RAG, and MCP
🎨 Developer-friendly: Clean APIs, opt-in tracing, OpenAI-compatible LLM support
🪶 Lightweight: No heavy dependencies; just Go and your choice of LLM provider

Features

🤝 Agent orchestration: Multi-agent workflows with role specialization and coordination
🧩 LLM abstraction: Work with OpenAI, Ollama, or any OpenAI-compatible endpoint
🛠️ Function tools: Expose Go functions as callable tools with automatic JSON Schema generation
📚 RAG (Retrieval-Augmented Generation): Built-in vector storage and semantic search
🧠 Skills system: Define reusable agent capabilities in SKILL.md files
🔌 MCP support: Integrate Model Context Protocol servers as agent tools
🧾 Memory management: Conversational context storage for agents
✂️ Text splitting: Document chunking for RAG workflows
🧬 Embeddings: Semantic search capabilities via OpenAI embeddings
🗄️ Vector stores: Vector database integration

Architecture

Agent Layer
- agent: Core orchestration for LLM-based agents with tool execution and chat loops
- memory: Conversational context management for multi-turn interactions
LLM Layer
- llm: Clean LLM interface with function tool support and JSON Schema utilities
- llm/openai: OpenAI-compatible client (works with OpenAI, Ollama, and compatible endpoints)
Knowledge Layer
- embedding: Embedding interface for semantic operations
- embedding/openai: OpenAI embeddings implementation
- vectorstore: Vector storage interface for similarity search
- vectorstore/qdrant: Qdrant vector database integration
- vectorstore/psql: PostgreSQL + pgvector integration
- textsplitter: Document chunking for RAG workflows
- rag: Complete RAG pipeline combining embeddings and vector stores
Tools & Integration
- skill: Parse SKILL.md files and expose them as agent capabilities
- mcp: Model Context Protocol adapter for external tool integration
- tool/file: File system operations
- tool/go: Safe Go command execution
- tool/python: Python script execution
- tool/human: Human-in-the-loop input collection

Examples

Example	Description
Simple Agent	Start here! Minimal example showing one agent with one custom tool perfect for learning the basics
Conversational Agent	REPL-style chatbot with short-term conversational memory and a simple built-in tool
Long-Term Memory	REPL-style chatbot with semantic long-term memory (RAG) backed by Qdrant
Debate Committee	Multi-agent architecture where committee members debate independently and a judge synthesizes the final decision
Multi-Agent Workflow	Classic Plan → Execute → Analyze → Critique pattern with specialized agent roles
RAG Chatbot	Terminal chatbot with semantic search over local documents using Qdrant
Skill	Discover SKILL.md files and expose them as callable agent tools
MCP Integration	Run an MCP server as a subprocess and expose its tools to agents
Supervisor Blackboard	Supervisor-worker pattern with a shared blackboard for coordination

Design Philosophy

Composability over monoliths: Each package does one thing well
Interfaces over implementations: Swap LLMs, vector stores, or embeddings easily
Explicit over implicit: No hidden magic; clear control flow
Tools are first-class: Function tools are the primary integration point
Developer experience matters: Clean APIs, helpful tracing, good error messages

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Acknowledgments

Built with ❤️ by Simone Vellei.

Inspired by the collaborative intelligence of ant colonies where independent agents work together toward shared goals, recognizing one another and coordinating through clear protocols.

The ant is not just a mascot. It is the philosophy. 🐜

🐜 Phero