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 + Anthropic support
🪶 Lightweight: No heavy dependencies; just Go and your choice of LLM provider

Features

🤝 Agent orchestration: Multi-agent workflows with role specialization, coordination, and handoffs
🧩 LLM abstraction: Work with OpenAI-compatible endpoints (OpenAI, Ollama, etc.) and Anthropic
🛠️ 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
🔍 Tracing: Observe agent, LLM, tool, and memory lifecycle events with colorized terminal output
✂️ 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 (in-process, file-backed, PostgreSQL-backed, or semantic RAG-backed)
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)
- llm/anthropic: Anthropic API client
Observability
- trace: Typed lifecycle events; human-readable text tracer (trace/text) and NDJSON file tracer (trace/jsonfile); also wraps raw LLM calls
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
- vectorstore/weaviate: Weaviate vector database integration
- textsplitter/recursive: Recursive character-based chunking
- textsplitter/markdown: Markdown-aware chunking (heading-first separators)
- 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/agent: Create and run a sub-agent at runtime as a delegated tool
- tool/file: Filesystem tools (read, write, edit, glob, grep)
- tool/bash: Bash command execution with guardrails (blocklist, allowlist, timeout, safe mode) and background execution
- tool/human: Structured user-interaction checkpoints with validated questions and options
- a2a: Agent-to-Agent (A2A) protocol server and client for inter-agent networking

Examples

Example	Description
Simple Agent	Start here! Minimal example showing one agent with one custom tool perfect for learning the basics
Multimodal	Send text + image inputs to a vision-capable model using typed content parts
Audio	End-to-end speech-to-text and text-to-speech using the OpenAI backend
LLM Middleware	Wrap an LLM with composable middleware for logging and other cross-cutting concerns
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
Handoff	One agent hands work off to a specialist agent at runtime using the built-in handoff mechanism
A2A Server	Expose a Phero agent as an A2A-compliant HTTP server for cross-process agent calls
A2A Client	Connect to a remote A2A agent and use it as a local tool inside an orchestrator
Debate Committee	Multi-agent architecture where committee members debate independently and a judge synthesizes the final decision
Evaluator-Optimizer	Iterative generation loop where an optimizer proposes drafts and an evaluator critiques them until quality criteria are met
Human-in-the-Loop	Multi-agent flow that pauses for explicit human approval before continuing each action
Multi-Agent Workflow	Classic Plan → Execute → Analyze → Critique pattern with specialized agent roles
Orchestrator-Workers	Dynamic task decomposition where an orchestrator delegates sub-tasks to worker agents
Parallel Research	Fan-out/fan-in workflow that runs multiple specialist researchers in parallel and merges their findings
Prompt Chaining	Sequential multi-step prompting with a programmatic gate between stages
RAG Chatbot	Terminal chatbot with semantic search over local documents using Qdrant
Skill	Use the tool/skill dispatcher to load SKILL.md instructions into the current conversation
Social Simulation	Multi-agent social simulation with persona-driven actors and emergent interactions
MCP Integration	Run an MCP server as a subprocess and expose its tools to agents
Playwright MCP	Connect browser automation tools through MCP and orchestrate them from an agent
Supervisor Blackboard	Supervisor-worker pattern with a shared blackboard for coordination
Tracing	Attach a colorized tracer to an agent and inspect LLM requests, tool calls, and memory events in real time

Tracing

Tracing is opt-in. Attach a tracer to an agent with SetTracer to observe typed events for agent lifecycle, LLM requests and responses, tool calls and results, and memory operations.

a.SetTracer(text.New(os.Stderr))

The built-in text tracer writes colorized, human-readable lines to the terminal. An NDJSON file tracer (jsonfile.New) is also available for structured log ingestion. See Trace for the full package overview and usage examples.

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