# boboiazumi/hans-agent architecture

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

- Interactive diagram: https://gitdiagram.com/boboiazumi/hans-agent
- Repository: https://github.com/boboiazumi/hans-agent

## Overview

Hans Agent is a plugin-based LangGraph multi-agent framework. A user enters through Gradio, Discord, or the roleplay API; each interface invokes the compiled conversation graph, which summarizes context, lets the supervisor answer or use tools, and can delegate or consult sub-agents before returning a response. Plugin tools add memory, weather, and Discord messaging; the roleplay API can optionally generate speech. The README documents automatic plugin discovery, while the sampled source shows graph construction and several interface/tool implementations; internal startup wiring beyond those sources is not expanded here.

Main entry points: [`src/core/graph.py`](https://github.com/boboiazumi/hans-agent/blob/main/src/core/graph.py) (Conversation graph), [`src/core/supervisor_think.py`](https://github.com/boboiazumi/hans-agent/blob/main/src/core/supervisor_think.py) (Supervisor reasoning), [`src/utils/state.py`](https://github.com/boboiazumi/hans-agent/blob/main/src/utils/state.py) (Conversation state), [`plugins/roleplay_api/service.py`](https://github.com/boboiazumi/hans-agent/blob/main/plugins/roleplay_api/service.py) (Roleplay API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gradio["Gradio chat<br/>[service.py]"]
  node_discord["Discord bot<br/>[service.py]"]
  node_roleplay["Roleplay API<br/>[service.py]"]
  node_tts["Speech generation<br/>[service.py]"]
end

subgraph group_coordination["Conversation orchestration"]
  node_main["Application startup<br/>[main.py]"]
  node_entrypoint["Graph and plugin setup<br/>[entrypoint.py]"]
  node_graph["Conversation graph<br/>[graph.py]"]
  node_summarize["Context summarization<br/>[summarize_node.py]"]
  node_supervisor["Supervisor reasoning"]
  node_decision["Answer or route<br/>[route_decision.py]"]
  node_dispatch["Agent dispatch"]
  node_finalize["Response finalization"]
  node_state["Conversation state<br/>[state.py]"]
end

subgraph group_agents["Agent runtime"]
  node_agents["Agent registry<br/>[agents.py]"]
end

subgraph group_plugins["Plugin capabilities"]
  node_library["Memory tool<br/>[service.py]"]
  node_milvus[("Milvus memory store<br/>[service.py]")]
  node_embeddings["Text embeddings<br/>[service.py]"]
  node_weather["Weather tool<br/>[service.py]"]
  node_discord_tool["Discord message tool<br/>[service.py]"]
end

node_user(("User"))
node_weather_service["Weather service"]
node_discord_service["Discord platform"]

node_user -->|"sends chat"| node_gradio
node_user -->|"sends message"| node_discord
node_user -->|"sends request"| node_roleplay
node_main -->|"starts setup"| node_entrypoint
node_entrypoint -->|"builds graph"| node_graph
node_entrypoint -->|"configures agents"| node_agents
node_graph -->|"builds agent graphs"| node_agents
node_graph -->|"dispatches node"| node_summarize
node_graph -->|"dispatches node"| node_supervisor
node_graph -->|"dispatches node"| node_decision
node_graph -->|"dispatches node"| node_dispatch
node_graph -->|"dispatches node"| node_finalize
node_summarize -->|"updates context"| node_state
node_supervisor -->|"reads and updates"| node_state
node_decision -->|"reads decision"| node_state
node_dispatch -->|"selects agent"| node_agents
node_finalize -->|"reads and updates"| node_state
node_gradio -->|"invokes"| node_graph
node_discord -->|"invokes"| node_graph
node_roleplay -->|"invokes"| node_graph
node_roleplay -.->|"generates speech"| node_tts
node_supervisor -->|"calls tool"| node_library
node_supervisor -->|"calls tool"| node_weather
node_supervisor -->|"calls tool"| node_discord_tool
node_library -->|"embeds text"| node_embeddings
node_library -->|"reads and writes"| node_milvus
node_weather -->|"requests forecast"| node_weather_service
node_discord_tool -->|"sends message"| node_discord_service

click node_main "https://github.com/boboiazumi/hans-agent/blob/main/main.py"
click node_entrypoint "https://github.com/boboiazumi/hans-agent/blob/main/src/core/entrypoint.py"
click node_graph "https://github.com/boboiazumi/hans-agent/blob/main/src/core/graph.py"
click node_summarize "https://github.com/boboiazumi/hans-agent/blob/main/src/core/summarize_node.py"
click node_supervisor "https://github.com/boboiazumi/hans-agent/blob/main/src/core/supervisor_think.py"
click node_decision "https://github.com/boboiazumi/hans-agent/blob/main/src/core/route_decision.py"
click node_dispatch "https://github.com/boboiazumi/hans-agent/blob/main/src/core/call_other_agent.py"
click node_finalize "https://github.com/boboiazumi/hans-agent/blob/main/src/core/supervisor_finalize.py"
click node_state "https://github.com/boboiazumi/hans-agent/blob/main/src/utils/state.py"
click node_agents "https://github.com/boboiazumi/hans-agent/blob/main/src/lib/agents.py"
click node_gradio "https://github.com/boboiazumi/hans-agent/blob/main/plugins/gradio/service.py"
click node_discord "https://github.com/boboiazumi/hans-agent/blob/main/plugins/discord/service.py"
click node_roleplay "https://github.com/boboiazumi/hans-agent/blob/main/plugins/roleplay_api/service.py"
click node_tts "https://github.com/boboiazumi/hans-agent/blob/main/plugins/roleplay_api/service.py"
click node_library "https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py"
click node_milvus "https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py"
click node_embeddings "https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py"
click node_weather "https://github.com/boboiazumi/hans-agent/blob/main/plugins/weather/service.py"
click node_discord_tool "https://github.com/boboiazumi/hans-agent/blob/main/plugins/discord/service.py"

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_gradio,node_discord,node_roleplay,node_tts,node_user toneBlue
class node_main,node_entrypoint,node_graph,node_summarize,node_supervisor,node_decision,node_dispatch,node_finalize,node_state toneAmber
class node_agents toneMint
class node_library,node_milvus,node_embeddings,node_weather,node_discord_tool toneRose
class node_weather_service,node_discord_service toneIndigo
```

## Components

### User interfaces

- [Gradio chat](https://github.com/boboiazumi/hans-agent/blob/main/plugins/gradio/service.py): `plugins/gradio/service.py`
- [Discord bot](https://github.com/boboiazumi/hans-agent/blob/main/plugins/discord/service.py): `plugins/discord/service.py`
- [Roleplay API](https://github.com/boboiazumi/hans-agent/blob/main/plugins/roleplay_api/service.py): `plugins/roleplay_api/service.py`
- [Speech generation](https://github.com/boboiazumi/hans-agent/blob/main/plugins/roleplay_api/service.py): `plugins/roleplay_api/service.py`

### Conversation orchestration

- [Application startup](https://github.com/boboiazumi/hans-agent/blob/main/main.py): `main.py`
- [Graph and plugin setup](https://github.com/boboiazumi/hans-agent/blob/main/src/core/entrypoint.py): `src/core/entrypoint.py`
- [Conversation graph](https://github.com/boboiazumi/hans-agent/blob/main/src/core/graph.py): `src/core/graph.py`
- [Context summarization](https://github.com/boboiazumi/hans-agent/blob/main/src/core/summarize_node.py): `src/core/summarize_node.py`
- [Supervisor reasoning](https://github.com/boboiazumi/hans-agent/blob/main/src/core/supervisor_think.py): `src/core/supervisor_think.py`
- [Answer or route](https://github.com/boboiazumi/hans-agent/blob/main/src/core/route_decision.py): `src/core/route_decision.py`
- [Agent dispatch](https://github.com/boboiazumi/hans-agent/blob/main/src/core/call_other_agent.py): `src/core/call_other_agent.py`
- [Response finalization](https://github.com/boboiazumi/hans-agent/blob/main/src/core/supervisor_finalize.py): `src/core/supervisor_finalize.py`
- [Conversation state](https://github.com/boboiazumi/hans-agent/blob/main/src/utils/state.py): `src/utils/state.py`

### Agent runtime

- [Agent registry](https://github.com/boboiazumi/hans-agent/blob/main/src/lib/agents.py): `src/lib/agents.py`

### Plugin capabilities

- [Memory tool](https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py): `plugins/library/service.py`
- [Milvus memory store](https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py): `plugins/library/service.py`
- [Text embeddings](https://github.com/boboiazumi/hans-agent/blob/main/plugins/library/service.py): `plugins/library/service.py`
- [Weather tool](https://github.com/boboiazumi/hans-agent/blob/main/plugins/weather/service.py): `plugins/weather/service.py`
- [Discord message tool](https://github.com/boboiazumi/hans-agent/blob/main/plugins/discord/service.py): `plugins/discord/service.py`

### Other components

- **User**
- **Weather service**
- **Discord platform**

## Connections

- User → Gradio chat: sends chat
- User → Discord bot: sends message
- User → Roleplay API: sends request
- Application startup → Graph and plugin setup: starts setup
- Graph and plugin setup → Conversation graph: builds graph
- Graph and plugin setup → Agent registry: configures agents
- Conversation graph → Agent registry: builds agent graphs
- Conversation graph → Context summarization: dispatches node
- Conversation graph → Supervisor reasoning: dispatches node
- Conversation graph → Answer or route: dispatches node
- Conversation graph → Agent dispatch: dispatches node
- Conversation graph → Response finalization: dispatches node
- Context summarization → Conversation state: updates context
- Supervisor reasoning → Conversation state: reads and updates
- Answer or route → Conversation state: reads decision
- Agent dispatch → Agent registry: selects agent
- Response finalization → Conversation state: reads and updates
- Gradio chat → Conversation graph: invokes
- Discord bot → Conversation graph: invokes
- Roleplay API → Conversation graph: invokes
- Roleplay API → Speech generation: generates speech
- Supervisor reasoning → Memory tool: calls tool
- Supervisor reasoning → Weather tool: calls tool
- Supervisor reasoning → Discord message tool: calls tool
- Memory tool → Text embeddings: embeds text
- Memory tool → Milvus memory store: reads and writes
- Weather tool → Weather service: requests forecast
- Discord message tool → Discord platform: sends message