# Phero

> A modern Go framework for building multi-agent AI systems.

- **Type:** MCP server
- **Install:** `agentstack add mcp-henomis-phero`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [henomis](https://agentstack.voostack.com/s/henomis)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [henomis](https://github.com/henomis)
- **Source:** https://github.com/henomis/phero
- **Website:** http://simonevellei.com/phero/

## Install

```sh
agentstack add mcp-henomis-phero
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🐜 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.

[](https://github.com/henomis/phero/actions/workflows/checks.yml) [](https://godoc.org/github.com/henomis/phero) [](https://goreportcard.com/report/github.com/henomis/phero) [](https://github.com/henomis/phero/releases)

## 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(...)` (retry, rate-limit, guardrails, and semantic response caching)
- **🛠️ 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`), an NDJSON file tracer (`trace/jsonfile`), and an OpenTelemetry tracer (`trace/otel`); 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](examples/simple-agent/)** example to learn the basics in ~100 lines of code.

Then try:
- **[Conversational Agent](examples/conversational-agent/)** a multi-turn REPL chatbot with short-term memory
- **[Long-Term Memory](examples/long-term-memory/)** semantic (RAG) memory backed by Qdrant

Then explore the **[examples/](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/otel` for OpenTelemetry spans; `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/`](examples/) directory:

| Example | Description |
|---|---|
| [Simple Agent](examples/simple-agent/) | **Start here!** Minimal example showing one agent with one custom tool perfect for learning the basics |
| [Streaming](examples/streaming/) | Stream an agent's response token-by-token with `Agent.RunStream`, including tool call/result events |
| [Multimodal](examples/multimodal/) | Send text + image inputs to a vision-capable model using typed content parts |
| [Audio](examples/audio/) | End-to-end speech-to-text and text-to-speech using the OpenAI backend |
| [LLM Middleware](examples/llm-middleware/) | Wrap an LLM with composable middleware for logging and other cross-cutting concerns |
| [Conversational Agent](examples/conversational-agent/) | REPL-style chatbot with short-term conversational memory and a simple built-in tool |
| [Long-Term Memory](examples/long-term-memory/) | REPL-style chatbot with semantic long-term memory (RAG) backed by Qdrant |
| [NATS Memory](examples/nats-memory/) | Persistent chatbot backed by NATS JetStream KV; conversation survives process restarts and supports named sessions |
| [Handoff](examples/handoff/) | One agent hands work off to a specialist agent at runtime using the built-in handoff mechanism |
| [A2A Server](examples/a2a/server/) | Expose a Phero agent as an A2A-compliant HTTP server for cross-process agent calls |
| [A2A Client](examples/a2a/client/) | Connect to a remote A2A agent and use it as a local tool inside an orchestrator |
| [A2A Multi-Agent Newsroom](examples/a2a/multi-agent/) | Three specialised agents (researcher, writer, editor) each running as an independent A2A server, coordinated by a local orchestrator |
| [NATS Agent](examples/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](examples/nats-agent/multi-agent/) | Three specialised agents running as NATS micro services, orchestrated via service discovery and `Client.AsTool()` |
| [Debate Committee](examples/debate-committee/) | Multi-agent architecture where committee members debate independently and a judge synthesizes the final decision |
| [Evaluator-Optimizer](examples/evaluator-optimizer/) | Iterative generation loop where an optimizer proposes drafts and an evaluator critiques them until quality criteria are met |
| [Human-in-the-Loop](examples/human-in-the-loop/) | Multi-agent flow that pauses for explicit human approval/input before continuing |
| [Multi-Agent Workflow](examples/multi-agent-workflow/) | Classic Plan → Execute → Analyze → Critique pattern with specialized agent roles |
| [Orchestrator-Workers](examples/orchestrator-workers/) | Dynamic task decomposition where an orchestrator delegates sub-tasks to worker agents |
| [Parallel Research](examples/parallel-research/) | Fan-out/fan-in workflow that runs multiple specialist researchers in parallel and merges their findings |
| [Prompt Chaining](examples/prompt-chaining/) | Sequential multi-step prompting with a programmatic gate between stages |
| [RAG Chatbot](examples/rag-chatbot/) | Terminal chatbot with semantic search over local documents using Qdrant |
| [Skill](examples/skills/) | Use the `tool/skill` dispatcher to load SKILL.md instructions into the current conversation |
| [Social Simulation](examples/social-simulation/) | Multi-agent social simulation with persona-driven actors and emergent interactions |
| [MCP Integration](examples/mcp/) | Run an MCP server as a subprocess and expose its tools to agents |
| [Playwright MCP](examples/playwright-mcp/) | Connect browser automation tools through MCP and orchestrate them from an agent |
| [Supervisor Blackboard](examples/supervisor-blackboard/) | Supervisor-worker pattern with a shared blackboard for coordination |
| [Tracing](examples/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](LICENSE) file for details.

## Acknowledgments

Built with ❤️ by [Simone Vellei](https://github.com/henomis).

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](https://pkg.go.dev/github.com/henomis/phero)
- **Issues**: [github.com/henomis/phero/issues](https://github.com/henomis/phero/issues)
- **Discussions**: [github.com/henomis/phero/discussions](https://github.com/henomis/phero/discussions)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [henomis](https://github.com/henomis)
- **Source:** [henomis/phero](https://github.com/henomis/phero)
- **License:** Apache-2.0
- **Homepage:** http://simonevellei.com/phero/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-henomis-phero
- Seller: https://agentstack.voostack.com/s/henomis
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.