# mytk2012/python_agent architecture

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

- Interactive diagram: https://gitdiagram.com/mytk2012/python_agent
- Repository: https://github.com/mytk2012/python_agent

## Overview

This repository is a Python AI-agent framework, exposed through a unified Application factory for library, CLI, web, and WebSocket modes. Its principal workflow accepts a user task, initializes AgentIntegration, routes the task and selects tools, executes an agent loop, and returns a response. Major documented branches include AgentScope, MCP/A2A, multi-agent coordination, memory, RAG, and evaluation. The graph combines README-level architecture with the sampled Application, LLM, RAG, and session-manager code; links for unsampled subsystems are limited to documented responsibilities.

Main entry points: [`integrate/agent.py`](https://github.com/mytk2012/python_agent/blob/main/integrate/agent.py) (Agent integration), [`products/application.py`](https://github.com/mytk2012/python_agent/blob/main/products/application.py) (Application), [`capabilities/tool_registry/tool_registry.py`](https://github.com/mytk2012/python_agent/blob/main/capabilities/tool_registry/tool_registry.py) (Tool registry), [`orchestration/loops`](https://github.com/mytk2012/python_agent/tree/main/orchestration/loops) (Agent loops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Product interfaces"]
  node_application["Application<br/>[application.py]"]
  node_web["REST API<br/>[web_server.py]"]
  node_websocket["WebSocket<br/>[ws_server.py]"]
  node_sessions["Session manager<br/>[session_manager.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_tui["Terminal UI<br/>[app.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_integration["Agent integration<br/>[agent.py]"]
  node_router["Task router<br/>[task_router.py]"]
  node_selector["Tool selector<br/>[tool_selector.py]"]
  node_loops["Agent loops"]
  node_multiagent["Multi-agent"]
  node_sdk["AgentScope adapter<br/>[adapter.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_registry["Tool registry<br/>[tool_registry.py]"]
  node_builtin["Built-in tools"]
  node_skills["Skills<br/>[skill_loader.py]"]
  node_mcp["MCP integration"]
  node_a2a["A2A integration"]
end

subgraph group_services["Models and state"]
  node_llm["LLM service<br/>[llm_service.py]"]
  node_embedding["Embedding service"]
  node_memory["Memory service<br/>[unified_service.py]"]
  node_rag["RAG pipeline<br/>[rag_pipeline.py]"]
  node_knowledge["Knowledge manager"]
end

subgraph group_extensions["Framework extensions"]
  node_evaluation["Evaluation<br/>[evaluator.py]"]
  node_eval_storage[("Evaluation storage<br/>[file_storage.py]")]
  node_hooks["Lifecycle hooks<br/>[executor.py]"]
  node_permissions["Permissions<br/>[checker.py]"]
  node_observability["Tracing and logs<br/>[tracing.py]"]
  node_queue["Execution queues<br/>[i_queue.py]"]
end

node_user(("User"))

node_user -->|"submits task"| node_application
node_application -->|"initializes and invokes"| node_integration
node_application -->|"starts by mode"| node_web
node_application -->|"starts by mode"| node_websocket
node_application -->|"starts by mode"| node_cli
node_application -->|"starts by mode"| node_tui
node_websocket -->|"manages sessions"| node_sessions
node_cli -->|"submits tasks"| node_integration
node_tui -->|"submits tasks"| node_integration
node_integration -->|"routes tasks"| node_router
node_integration -->|"selects tools"| node_selector
node_integration -->|"executes tasks"| node_loops
node_integration -->|"checks access"| node_permissions
node_integration -->|"runs hooks"| node_hooks
node_integration -->|"integrates evaluation"| node_evaluation
node_integration -->|"tracks execution"| node_observability
node_loops -->|"requests completions"| node_llm
node_loops -->|"uses tools"| node_registry
node_selector -->|"selects from"| node_registry
node_registry -->|"registers tools"| node_builtin
node_registry -->|"registers dynamic tools"| node_skills
node_registry -->|"exposes MCP tools"| node_mcp
node_multiagent -.->|"communicates remotely"| node_a2a
node_sdk -.->|"supports model-backed agents"| node_llm
node_integration -.->|"supports collaboration"| node_multiagent
node_integration -.->|"supports SDK mode"| node_sdk
node_sessions -->|"creates session memory"| node_memory
node_rag -->|"creates and retrieves"| node_knowledge
node_rag -->|"generates answers"| node_llm
node_knowledge -->|"embeds content"| node_embedding
node_evaluation -->|"persists results"| node_eval_storage
node_integration -.->|"supports concurrent execution"| node_queue

click node_application "https://github.com/mytk2012/python_agent/blob/main/products/application.py"
click node_web "https://github.com/mytk2012/python_agent/blob/main/interface/web/web_server.py"
click node_websocket "https://github.com/mytk2012/python_agent/blob/main/interface/websocket/ws_server.py"
click node_sessions "https://github.com/mytk2012/python_agent/blob/main/interface/websocket/session_manager.py"
click node_cli "https://github.com/mytk2012/python_agent/blob/main/interface/cli/cli.py"
click node_tui "https://github.com/mytk2012/python_agent/blob/main/interface/cli_tui/app.py"
click node_integration "https://github.com/mytk2012/python_agent/blob/main/integrate/agent.py"
click node_router "https://github.com/mytk2012/python_agent/blob/main/orchestration/router/task_router.py"
click node_selector "https://github.com/mytk2012/python_agent/blob/main/orchestration/router/tool_selector.py"
click node_loops "https://github.com/mytk2012/python_agent/tree/main/orchestration/loops"
click node_multiagent "https://github.com/mytk2012/python_agent/blob/main/orchestration/multi_agent/multi_agent_coordinator.py"
click node_sdk "https://github.com/mytk2012/python_agent/blob/main/agent_sdk/agent_scope/adapter.py"
click node_registry "https://github.com/mytk2012/python_agent/blob/main/capabilities/tool_registry/tool_registry.py"
click node_builtin "https://github.com/mytk2012/python_agent/tree/main/capabilities/tools"
click node_skills "https://github.com/mytk2012/python_agent/blob/main/capabilities/skills/skill_loader.py"
click node_mcp "https://github.com/mytk2012/python_agent/blob/main/capabilities/mcp/mcp_client_manager.py"
click node_a2a "https://github.com/mytk2012/python_agent/blob/main/capabilities/a2a/a2a_client_manager.py"
click node_llm "https://github.com/mytk2012/python_agent/blob/main/model_services/llm/llm_service.py"
click node_embedding "https://github.com/mytk2012/python_agent/blob/main/model_services/embedding/embedding_service.py"
click node_memory "https://github.com/mytk2012/python_agent/blob/main/state_management/memory/unified_service.py"
click node_rag "https://github.com/mytk2012/python_agent/blob/main/rag/rag/rag_pipeline.py"
click node_knowledge "https://github.com/mytk2012/python_agent/blob/main/rag/embedding/knowledge_base_manager.py"
click node_evaluation "https://github.com/mytk2012/python_agent/blob/main/evaluation/core/evaluator.py"
click node_eval_storage "https://github.com/mytk2012/python_agent/blob/main/evaluation/storage/file_storage.py"
click node_hooks "https://github.com/mytk2012/python_agent/blob/main/foundation/hooks/executor.py"
click node_permissions "https://github.com/mytk2012/python_agent/blob/main/foundation/permissions/checker.py"
click node_observability "https://github.com/mytk2012/python_agent/blob/main/foundation/observability/tracing.py"
click node_queue "https://github.com/mytk2012/python_agent/blob/main/foundation/queue/i_queue.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_application,node_web,node_websocket,node_sessions,node_cli,node_tui,node_user toneBlue
class node_integration,node_router,node_selector,node_loops,node_multiagent,node_sdk toneAmber
class node_registry,node_builtin,node_skills,node_mcp,node_a2a toneMint
class node_llm,node_embedding,node_memory,node_rag,node_knowledge toneRose
class node_evaluation,node_eval_storage,node_hooks,node_permissions,node_observability,node_queue toneIndigo
```

## Components

### Product interfaces

- [Application](https://github.com/mytk2012/python_agent/blob/main/products/application.py): `products/application.py`
- [REST API](https://github.com/mytk2012/python_agent/blob/main/interface/web/web_server.py): `interface/web/web_server.py`
- [WebSocket](https://github.com/mytk2012/python_agent/blob/main/interface/websocket/ws_server.py): `interface/websocket/ws_server.py`
- [Session manager](https://github.com/mytk2012/python_agent/blob/main/interface/websocket/session_manager.py): `interface/websocket/session_manager.py`
- [CLI](https://github.com/mytk2012/python_agent/blob/main/interface/cli/cli.py): `interface/cli/cli.py`
- [Terminal UI](https://github.com/mytk2012/python_agent/blob/main/interface/cli_tui/app.py): `interface/cli_tui/app.py`

### Agent runtime

- [Agent integration](https://github.com/mytk2012/python_agent/blob/main/integrate/agent.py): `integrate/agent.py`
- [Task router](https://github.com/mytk2012/python_agent/blob/main/orchestration/router/task_router.py): `orchestration/router/task_router.py`
- [Tool selector](https://github.com/mytk2012/python_agent/blob/main/orchestration/router/tool_selector.py): `orchestration/router/tool_selector.py`
- [Agent loops](https://github.com/mytk2012/python_agent/tree/main/orchestration/loops): `orchestration/loops`
- [Multi-agent](https://github.com/mytk2012/python_agent/blob/main/orchestration/multi_agent/multi_agent_coordinator.py): `orchestration/multi_agent/multi_agent_coordinator.py`
- [AgentScope adapter](https://github.com/mytk2012/python_agent/blob/main/agent_sdk/agent_scope/adapter.py): `agent_sdk/agent_scope/adapter.py`

### Agent capabilities

- [Tool registry](https://github.com/mytk2012/python_agent/blob/main/capabilities/tool_registry/tool_registry.py): `capabilities/tool_registry/tool_registry.py`
- [Built-in tools](https://github.com/mytk2012/python_agent/tree/main/capabilities/tools): `capabilities/tools`
- [Skills](https://github.com/mytk2012/python_agent/blob/main/capabilities/skills/skill_loader.py): `capabilities/skills/skill_loader.py`
- [MCP integration](https://github.com/mytk2012/python_agent/blob/main/capabilities/mcp/mcp_client_manager.py): `capabilities/mcp/mcp_client_manager.py`
- [A2A integration](https://github.com/mytk2012/python_agent/blob/main/capabilities/a2a/a2a_client_manager.py): `capabilities/a2a/a2a_client_manager.py`

### Models and state

- [LLM service](https://github.com/mytk2012/python_agent/blob/main/model_services/llm/llm_service.py): `model_services/llm/llm_service.py`
- [Embedding service](https://github.com/mytk2012/python_agent/blob/main/model_services/embedding/embedding_service.py): `model_services/embedding/embedding_service.py`
- [Memory service](https://github.com/mytk2012/python_agent/blob/main/state_management/memory/unified_service.py): `state_management/memory/unified_service.py`
- [RAG pipeline](https://github.com/mytk2012/python_agent/blob/main/rag/rag/rag_pipeline.py): `rag/rag/rag_pipeline.py`
- [Knowledge manager](https://github.com/mytk2012/python_agent/blob/main/rag/embedding/knowledge_base_manager.py): `rag/embedding/knowledge_base_manager.py`

### Framework extensions

- [Evaluation](https://github.com/mytk2012/python_agent/blob/main/evaluation/core/evaluator.py): `evaluation/core/evaluator.py`
- [Evaluation storage](https://github.com/mytk2012/python_agent/blob/main/evaluation/storage/file_storage.py): `evaluation/storage/file_storage.py`
- [Lifecycle hooks](https://github.com/mytk2012/python_agent/blob/main/foundation/hooks/executor.py): `foundation/hooks/executor.py`
- [Permissions](https://github.com/mytk2012/python_agent/blob/main/foundation/permissions/checker.py): `foundation/permissions/checker.py`
- [Tracing and logs](https://github.com/mytk2012/python_agent/blob/main/foundation/observability/tracing.py): `foundation/observability/tracing.py`
- [Execution queues](https://github.com/mytk2012/python_agent/blob/main/foundation/queue/i_queue.py): `foundation/queue/i_queue.py`

### Other components

- **User**

## Connections

- User → Application: submits task
- Application → Agent integration: initializes and invokes
- Application → REST API: starts by mode
- Application → WebSocket: starts by mode
- Application → CLI: starts by mode
- Application → Terminal UI: starts by mode
- WebSocket → Session manager: manages sessions
- CLI → Agent integration: submits tasks
- Terminal UI → Agent integration: submits tasks
- Agent integration → Task router: routes tasks
- Agent integration → Tool selector: selects tools
- Agent integration → Agent loops: executes tasks
- Agent integration → Permissions: checks access
- Agent integration → Lifecycle hooks: runs hooks
- Agent integration → Evaluation: integrates evaluation
- Agent integration → Tracing and logs: tracks execution
- Agent loops → LLM service: requests completions
- Agent loops → Tool registry: uses tools
- Tool selector → Tool registry: selects from
- Tool registry → Built-in tools: registers tools
- Tool registry → Skills: registers dynamic tools
- Tool registry → MCP integration: exposes MCP tools
- Multi-agent → A2A integration: communicates remotely
- AgentScope adapter → LLM service: supports model-backed agents
- Agent integration → Multi-agent: supports collaboration
- Agent integration → AgentScope adapter: supports SDK mode
- Session manager → Memory service: creates session memory
- RAG pipeline → Knowledge manager: creates and retrieves
- RAG pipeline → LLM service: generates answers
- Knowledge manager → Embedding service: embeds content
- Evaluation → Evaluation storage: persists results
- Agent integration → Execution queues: supports concurrent execution