🐜 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
• 🔀 NATS Agent Protocol Register agents as NATS micro services and discover/call them over pub/sub; wire-compatible with TypeScript and Python SDKs
• 🧩 LLM abstraction Work with OpenAI-compatible endpoints (OpenAI, Ollama, etc.) and Anthropic
• 🖼️ Multimodal input Mix text and images with typed content parts (llm.Text, llm.ImageURL, llm.ImageFile)
• 🔊 Audio I/O OpenAI backend supports speech-to-text and text-to-speech via llm.Transcriber and llm.SpeechSynthesizer
• 🧱 LLM middleware Compose reusable cross-cutting behaviors around any backend with llm.Use(...)
• 🛠️ 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
• Multimodal and audio pipelines
• 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, PostgreSQL-backed, or NATS JetStream KV-backed)

💬 LLM Layer

• llm Provider-agnostic chat interface with typed messages/content parts, function tools, JSON Schema utilities, audio interfaces, and LLM middleware composition
• 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
• nats NATS Agent Protocol v0.3 — register agents as NATS micro services; discover and call them over pub/sub
• 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/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 (RunInBackground, bash_output, kill_shell)
• tool/human Structured user-interaction checkpoints; caller provides the interactor via WithInteractor
• tool/skill Dispatcher-style SKILL.md loader tool that expands instructions in the main conversation

Examples

Comprehensive examples are included in the examples/ directory:

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
NATS Memory	Persistent chatbot backed by NATS JetStream KV; conversation survives process restarts and supports named sessions
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
A2A Multi-Agent Newsroom	Three specialised agents (researcher, writer, editor) each running as an independent A2A server, coordinated by a local orchestrator
NATS Agent	Register a Phero agent as a NATS micro service and interact with it from an interactive client using the NATS Agent Protocol
NATS Multi-Agent Newsroom	Three specialised agents running as NATS micro services, orchestrated via service discovery and Client.AsTool()
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/input before continuing
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

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