🐜 Phero

The chemical language of AI agents.

Phero is a modern Go framework for building multi-agent AI systems. Like ants in a colony, agents in Phero cooperate, communicate, and coordinate toward shared goals, each with specialized roles, working together through a clean, composable architecture.

Why Phero?

• 🤝 Agent orchestration Multi-agent workflows with role specialization, coordination, and agent handoffs
• 🧩 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

Core Capabilities

• 🤝 Agent orchestration Multi-agent workflows with role specialization, coordination, and runtime handoffs
• 🔀 Agent handoffs Transfer control between agents at runtime; Result.HandoffAgent tells you where to route next
• 🌐 A2A protocol Expose any agent as an HTTP A2A server, or call remote A2A agents as local tools
• 🧩 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 Typed lifecycle events with a colorized text tracer (trace/text) and an NDJSON file tracer (trace/jsonfile); per-run summary with token usage and latency breakdowns
• 🛡️ Tool guardrails Bash tool blocklist, allowlist, timeout, and safe-mode options
• ✂️ Text splitting Recursive and Markdown-aware chunkers under textsplitter/recursive and textsplitter/markdown
• 🧬 Embeddings Semantic search capabilities via OpenAI embeddings
• 🗄️ Vector stores Qdrant, PostgreSQL/pgvector, and Weaviate backends

Requirements

• Go 1.25.5 or later
• An LLM provider (OpenAI / Ollama / OpenAI-compatible endpoint, or Anthropic)

Quick Start

Start with the Simple Agent example to learn the basics in ~100 lines of code.

Then try:

• Conversational Agent a multi-turn REPL chatbot with short-term memory
• Long-Term Memory semantic (RAG) memory backed by Qdrant

Then explore the examples/ directory for more advanced patterns:

• Multi-agent workflows
• RAG chatbots
• Skills integration
• MCP server connections

Some examples require extra services (e.g. Qdrant for vector search).

Architecture

Phero is organized into focused packages, each solving a specific problem:

🤖 Agent Layer

• agent Core orchestration for LLM-based agents with tool execution, chat loops, and runtime handoffs
• memory Conversational context management for multi-turn interactions (in-process, file-backed, RAG-backed, or PostgreSQL-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

🧠 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 Text splitting interface and shared types
• textsplitter/recursive Recursive character-based chunker
• textsplitter/markdown Markdown-aware chunker (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
• a2a Agent-to-Agent (A2A) protocol — expose agents as HTTP servers or call remote agents as tools
• trace Typed observability events; trace/text for human-readable colorized output; trace/jsonfile for NDJSON file logging; trace.NewLLM for raw LLM call wrapping
• tool/file File viewing and editing helpers (view, create_file with optional no-overwrite, str_replace)
• tool/bash Bash command execution with blocklist, allowlist, timeout, and safe-mode guardrails
• tool/human Human-in-the-loop input collection

Examples

Comprehensive examples are included in the examples/ directory:

Design Philosophy

Phero embraces several core principles:

1. Composability over monoliths Each package does one thing well
2. Interfaces over implementations Swap LLMs, vector stores, or embeddings easily
3. Explicit over implicit No hidden magic; clear control flow
4. Tools are first-class Function tools are the primary integration point
5. 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. 🐜

Links

• Documentation: pkg.go.dev/github.com/henomis/phero
• Issues: github.com/henomis/phero/issues
• Discussions: github.com/henomis/phero/discussions