# henomis/phero architecture

> Architecture diagram of the GitHub repository henomis/phero, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/henomis/phero
- Repository: https://github.com/henomis/phero

## Overview

Phero is a Go framework for building multi-agent AI systems. A typical run starts with an application invoking an agent, which coordinates model calls and tools and can use conversational memory; the application then routes any reported handoffs. The framework also exposes agents remotely through A2A or NATS, and provides a separate RAG path for ingesting and retrieving knowledge. Provider adapters, vector stores, and tracing are supporting layers. Relationships for unsampled capabilities are included only where the README documents them; source-level wiring is cited where excerpts or the source index show it.

Main entry points: [`agent/agent.go`](https://github.com/henomis/phero/blob/main/agent/agent.go) (Agent runtime), [`llm/llm.go`](https://github.com/henomis/phero/blob/main/llm/llm.go) (LLM interface), [`trace/processor.go`](https://github.com/henomis/phero/blob/main/trace/processor.go) (Trace core), [`vectorstore/vectorstore.go`](https://github.com/henomis/phero/blob/main/vectorstore/vectorstore.go) (Vector store API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent runtime<br/>[agent.go]"]
  node_memory["Conversation memory<br/>[memory.go]"]
  node_handoff["Handoff routing<br/>[agent.go]"]
end

subgraph group_models["LLM services"]
  node_llm["LLM interface<br/>[llm.go]"]
  node_openai["OpenAI adapter<br/>[openai.go]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.go]"]
  node_google["Google adapter<br/>[convert.go]"]
  node_middleware["LLM middleware<br/>[cache.go]"]
end

subgraph group_knowledge["Knowledge and memory"]
  node_embedding["Embeddings<br/>[embedding.go]"]
  node_rag["RAG pipeline<br/>[rag.go]"]
  node_splitter["Text splitting<br/>[textsplitter.go]"]
  node_vectorstore["Vector store API<br/>[vectorstore.go]"]
  node_qdrant["Qdrant store<br/>[qdrant.go]"]
  node_psqlvector["Postgres vector store<br/>[psql.go]"]
  node_weaviate["Weaviate store<br/>[weaviate.go]"]
  node_natsmemory[("NATS memory<br/>[memory.go]")]
end

subgraph group_integrations["Tools and protocols"]
  node_a2aserver["A2A server<br/>[server.go]"]
  node_a2aclient["A2A client<br/>[client.go]"]
  node_natssrv["NATS agent server<br/>[server.go]"]
  node_natsclient["NATS agent client<br/>[client.go]"]
  node_mcp["MCP adapter<br/>[mcp.go]"]
  node_skills["Skills<br/>[skill.go]"]
  node_skilltool["Skill tool<br/>[tool.go]"]
  node_bash["Bash tool<br/>[bash.go]"]
  node_filetool["Filesystem tools<br/>[read.go]"]
  node_webtool["Web tool<br/>[web.go]"]
  node_permission["Tool guardrails<br/>[permission.go]"]
end

subgraph group_observability["Tracing"]
  node_trace["Trace core<br/>[processor.go]"]
  node_otel["OpenTelemetry export<br/>[attributes.go]"]
  node_tracejson["NDJSON export<br/>[jsonfile.go]"]
  node_tracetext["Text trace view<br/>[text.go]"]
end

node_application(("Application"))

node_application -->|"invokes"| node_agent
node_agent -->|"calls model"| node_llm
node_agent -->|"uses context"| node_memory
node_agent -->|"reports handoffs"| node_handoff
node_application -->|"routes next"| node_handoff
node_llm -->|"implemented by"| node_openai
node_llm -->|"implemented by"| node_anthropic
node_llm -->|"implemented by"| node_google
node_llm -->|"wrapped by"| node_middleware
node_agent -->|"records spans"| node_trace
node_rag -->|"embeds text"| node_embedding
node_rag -->|"queries and writes"| node_vectorstore
node_rag -->|"splits documents"| node_splitter
node_vectorstore -->|"implemented by"| node_qdrant
node_vectorstore -->|"implemented by"| node_psqlvector
node_vectorstore -->|"implemented by"| node_weaviate
node_agent -->|"uses memory"| node_natsmemory
node_a2aserver -->|"exposes"| node_agent
node_a2aclient -->|"creates tool"| node_llm
node_natssrv -->|"runs handler"| node_agent
node_natsclient -->|"creates tool"| node_llm
node_mcp -->|"creates tools"| node_llm
node_skilltool -->|"loads skills"| node_skills
node_agent -->|"runs tool"| node_bash
node_agent -->|"runs tool"| node_filetool
node_agent -->|"runs tool"| node_webtool
node_agent -->|"guards tools"| node_permission
node_trace -->|"exports spans"| node_otel
node_trace -->|"writes NDJSON"| node_tracejson
node_trace -->|"renders tree"| node_tracetext
node_trace -->|"instruments calls"| node_llm

click node_agent "https://github.com/henomis/phero/blob/main/agent/agent.go"
click node_memory "https://github.com/henomis/phero/blob/main/memory/memory.go"
click node_handoff "https://github.com/henomis/phero/blob/main/agent/agent.go"
click node_llm "https://github.com/henomis/phero/blob/main/llm/llm.go"
click node_openai "https://github.com/henomis/phero/blob/main/llm/openai/openai.go"
click node_anthropic "https://github.com/henomis/phero/blob/main/llm/anthropic/anthropic.go"
click node_google "https://github.com/henomis/phero/blob/main/llm/google/convert.go"
click node_middleware "https://github.com/henomis/phero/blob/main/llm/middleware/cache.go"
click node_embedding "https://github.com/henomis/phero/blob/main/embedding/embedding.go"
click node_rag "https://github.com/henomis/phero/blob/main/rag/rag.go"
click node_splitter "https://github.com/henomis/phero/blob/main/textsplitter/textsplitter.go"
click node_vectorstore "https://github.com/henomis/phero/blob/main/vectorstore/vectorstore.go"
click node_qdrant "https://github.com/henomis/phero/blob/main/vectorstore/qdrant/qdrant.go"
click node_psqlvector "https://github.com/henomis/phero/blob/main/vectorstore/psql/psql.go"
click node_weaviate "https://github.com/henomis/phero/blob/main/vectorstore/weaviate/weaviate.go"
click node_natsmemory "https://github.com/henomis/phero/blob/main/memory/nats/memory.go"
click node_a2aserver "https://github.com/henomis/phero/blob/main/a2a/server.go"
click node_a2aclient "https://github.com/henomis/phero/blob/main/a2a/client.go"
click node_natssrv "https://github.com/henomis/phero/blob/main/nats/server.go"
click node_natsclient "https://github.com/henomis/phero/blob/main/nats/client.go"
click node_mcp "https://github.com/henomis/phero/blob/main/mcp/mcp.go"
click node_skills "https://github.com/henomis/phero/blob/main/skill/skill.go"
click node_skilltool "https://github.com/henomis/phero/blob/main/tool/skill/tool.go"
click node_bash "https://github.com/henomis/phero/blob/main/tool/bash/bash.go"
click node_filetool "https://github.com/henomis/phero/blob/main/tool/file/read.go"
click node_webtool "https://github.com/henomis/phero/blob/main/tool/web/web.go"
click node_permission "https://github.com/henomis/phero/blob/main/tool/permission/permission.go"
click node_trace "https://github.com/henomis/phero/blob/main/trace/processor.go"
click node_otel "https://github.com/henomis/phero/blob/main/trace/otel/attributes.go"
click node_tracejson "https://github.com/henomis/phero/blob/main/trace/jsonfile/jsonfile.go"
click node_tracetext "https://github.com/henomis/phero/blob/main/trace/text/text.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_memory,node_handoff toneBlue
class node_llm,node_openai,node_anthropic,node_google,node_middleware toneAmber
class node_embedding,node_rag,node_splitter,node_vectorstore,node_qdrant,node_psqlvector,node_weaviate,node_natsmemory toneMint
class node_a2aserver,node_a2aclient,node_natssrv,node_natsclient,node_mcp,node_skills,node_skilltool,node_bash,node_filetool,node_webtool,node_permission toneRose
class node_trace,node_otel,node_tracejson,node_tracetext,node_application toneIndigo
```

## Components

### Agent orchestration

- [Agent runtime](https://github.com/henomis/phero/blob/main/agent/agent.go): `agent/agent.go`
- [Conversation memory](https://github.com/henomis/phero/blob/main/memory/memory.go): `memory/memory.go`
- [Handoff routing](https://github.com/henomis/phero/blob/main/agent/agent.go): `agent/agent.go`

### LLM services

- [LLM interface](https://github.com/henomis/phero/blob/main/llm/llm.go): `llm/llm.go`
- [OpenAI adapter](https://github.com/henomis/phero/blob/main/llm/openai/openai.go): `llm/openai/openai.go`
- [Anthropic adapter](https://github.com/henomis/phero/blob/main/llm/anthropic/anthropic.go): `llm/anthropic/anthropic.go`
- [Google adapter](https://github.com/henomis/phero/blob/main/llm/google/convert.go): `llm/google/convert.go`
- [LLM middleware](https://github.com/henomis/phero/blob/main/llm/middleware/cache.go): `llm/middleware/cache.go`

### Knowledge and memory

- [Embeddings](https://github.com/henomis/phero/blob/main/embedding/embedding.go): `embedding/embedding.go`
- [RAG pipeline](https://github.com/henomis/phero/blob/main/rag/rag.go): `rag/rag.go`
- [Text splitting](https://github.com/henomis/phero/blob/main/textsplitter/textsplitter.go): `textsplitter/textsplitter.go`
- [Vector store API](https://github.com/henomis/phero/blob/main/vectorstore/vectorstore.go): `vectorstore/vectorstore.go`
- [Qdrant store](https://github.com/henomis/phero/blob/main/vectorstore/qdrant/qdrant.go): `vectorstore/qdrant/qdrant.go`
- [Postgres vector store](https://github.com/henomis/phero/blob/main/vectorstore/psql/psql.go): `vectorstore/psql/psql.go`
- [Weaviate store](https://github.com/henomis/phero/blob/main/vectorstore/weaviate/weaviate.go): `vectorstore/weaviate/weaviate.go`
- [NATS memory](https://github.com/henomis/phero/blob/main/memory/nats/memory.go): `memory/nats/memory.go`

### Tools and protocols

- [A2A server](https://github.com/henomis/phero/blob/main/a2a/server.go): `a2a/server.go`
- [A2A client](https://github.com/henomis/phero/blob/main/a2a/client.go): `a2a/client.go`
- [NATS agent server](https://github.com/henomis/phero/blob/main/nats/server.go): `nats/server.go`
- [NATS agent client](https://github.com/henomis/phero/blob/main/nats/client.go): `nats/client.go`
- [MCP adapter](https://github.com/henomis/phero/blob/main/mcp/mcp.go): `mcp/mcp.go`
- [Skills](https://github.com/henomis/phero/blob/main/skill/skill.go): `skill/skill.go`
- [Skill tool](https://github.com/henomis/phero/blob/main/tool/skill/tool.go): `tool/skill/tool.go`
- [Bash tool](https://github.com/henomis/phero/blob/main/tool/bash/bash.go): `tool/bash/bash.go`
- [Filesystem tools](https://github.com/henomis/phero/blob/main/tool/file/read.go): `tool/file/read.go`
- [Web tool](https://github.com/henomis/phero/blob/main/tool/web/web.go): `tool/web/web.go`
- [Tool guardrails](https://github.com/henomis/phero/blob/main/tool/permission/permission.go): `tool/permission/permission.go`

### Tracing

- [Trace core](https://github.com/henomis/phero/blob/main/trace/processor.go): `trace/processor.go`
- [OpenTelemetry export](https://github.com/henomis/phero/blob/main/trace/otel/attributes.go): `trace/otel/attributes.go`
- [NDJSON export](https://github.com/henomis/phero/blob/main/trace/jsonfile/jsonfile.go): `trace/jsonfile/jsonfile.go`
- [Text trace view](https://github.com/henomis/phero/blob/main/trace/text/text.go): `trace/text/text.go`

### Other components

- **Application**

## Connections

- Application → Agent runtime: invokes
- Agent runtime → LLM interface: calls model
- Agent runtime → Conversation memory: uses context
- Agent runtime → Handoff routing: reports handoffs
- Application → Handoff routing: routes next
- LLM interface → OpenAI adapter: implemented by
- LLM interface → Anthropic adapter: implemented by
- LLM interface → Google adapter: implemented by
- LLM interface → LLM middleware: wrapped by
- Agent runtime → Trace core: records spans
- RAG pipeline → Embeddings: embeds text (evidence: `rag/rag.go`)
- RAG pipeline → Vector store API: queries and writes (evidence: `rag/rag.go`)
- RAG pipeline → Text splitting: splits documents
- Vector store API → Qdrant store: implemented by
- Vector store API → Postgres vector store: implemented by
- Vector store API → Weaviate store: implemented by
- Agent runtime → NATS memory: uses memory
- A2A server → Agent runtime: exposes (evidence: `a2a/server.go`)
- A2A client → LLM interface: creates tool (evidence: `a2a/client.go`)
- NATS agent server → Agent runtime: runs handler (evidence: `nats/server.go`)
- NATS agent client → LLM interface: creates tool (evidence: `nats/client.go`)
- MCP adapter → LLM interface: creates tools (evidence: `mcp/mcp.go`)
- Skill tool → Skills: loads skills
- Agent runtime → Bash tool: runs tool
- Agent runtime → Filesystem tools: runs tool
- Agent runtime → Web tool: runs tool
- Agent runtime → Tool guardrails: guards tools
- Trace core → OpenTelemetry export: exports spans
- Trace core → NDJSON export: writes NDJSON
- Trace core → Text trace view: renders tree
- Trace core → LLM interface: instruments calls
