🐜 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 and Google Gemini 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.Handoffs tells you where to route next and with what context (more than one means fan-out)
• 🌐 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.), Anthropic and Google Gemini
• 🖼️ 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 Span tree of every run (agent, model calls, tools, handoffs, memory, retrieval, middleware) with full typed payloads; colorized text tree (trace/text), NDJSON (trace/jsonfile) and OpenTelemetry export following the GenAI semantic conventions (trace/otel); per-run summary with stop reason, token usage and cost (sub-agents included) 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, Anthropic, or Google Gemini)

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
• llm/google Google Gemini API client (official google.golang.org/genai SDK)

🧠 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

This is the beginning of the README. Read the rest at the original. Read the full README ↗