# exileline/exile-agent architecture

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

- Interactive diagram: https://gitdiagram.com/exileline/exile-agent
- Repository: https://github.com/exileline/exile-agent

## Overview

exile-agent is a FastAPI/PydanticAI runtime platform for configurable agents, governed tools, and multi-turn chat. The principal workflow is a chat request through the agent API and chat service into the runtime runner, where routing, history, skills, MCP toolsets, and approvals contribute to a response or resumable run. A parallel control-plane workflow manages model/provider, agent, MCP, and binding configuration through API services and database storage. README statements establish several runtime links; unsampled modules are represented only where their capabilities and paths are documented.

Main entry points: [`app/ai/runtime/runner.py`](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/runner.py) (Run orchestrator), [`app/ai/config_store/repository.py`](https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/repository.py) (Config repository), [`app/ai/services/config_admin_service.py`](https://github.com/exileline/exile-agent/blob/main/app/ai/services/config_admin_service.py) (Config admin), [`app/api/v1/endpoints/agent.py`](https://github.com/exileline/exile-agent/blob/main/app/api/v1/endpoints/agent.py) (Agent endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_agent_api["Agent endpoints<br/>[agent.py]"]
  node_config_api["Config endpoints<br/>[ai_config.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_runtime_manager["Runtime manager<br/>[manager.py]"]
  node_agent_registry["Agent registry<br/>[registry.py]"]
  node_agent_router["Agent router<br/>[agent_router.py]"]
  node_runner["Run orchestrator<br/>[runner.py]"]
end

subgraph group_capabilities["Runtime Capabilities"]
  node_history[("Session history<br/>[history.py]")]
  node_approvals[("Approval resume<br/>[approvals.py]")]
  node_skills["Skills injection<br/>[resolver.py]"]
  node_skill_registry["Skill catalog<br/>[registry.py]"]
  node_mcp_manager["MCP manager<br/>[manager.py]"]
  node_toolsets["Tool governance"]
end

subgraph group_control["Configuration Control"]
  node_config_service["Config admin"]
  node_capability_resolver["Capability resolver<br/>[resolver.py]"]
  node_config_repository["Config repository<br/>[repository.py]"]
  node_config_models["Config records<br/>[models.py]"]
  node_secret_encryption["Secret encryption<br/>[encryption.py]"]
end

node_developer(("API caller"))
node_external_model{{"Model provider"}}
node_database[("SQL database")]

node_developer -->|"submits chat"| node_agent_api
node_agent_api -->|"dispatches chat"| node_chat_service
node_chat_service -->|"runs request"| node_runner
node_runner -.->|"gets agent"| node_runtime_manager
node_runtime_manager -->|"builds agent"| node_agent_registry
node_runner -->|"routes request"| node_agent_router
node_runner -->|"loads and saves"| node_history
node_runner -->|"pauses and resumes"| node_approvals
node_runner -->|"resolves skills"| node_skills
node_skills -.->|"selects skills"| node_skill_registry
node_runner -->|"assembles MCP"| node_mcp_manager
node_mcp_manager -->|"wraps toolsets"| node_toolsets
node_runner -->|"invokes model"| node_external_model
node_developer -->|"manages config"| node_config_api
node_config_api -->|"delegates admin"| node_config_service
node_config_service -->|"reads and writes"| node_config_repository
node_config_service -->|"encrypts secrets"| node_secret_encryption
node_config_repository -->|"persists records"| node_config_models
node_config_repository -.->|"queries database"| node_database
node_capability_resolver -.->|"loads settings"| node_config_repository
node_runner -->|"resolves capabilities"| node_capability_resolver

click node_agent_api "https://github.com/exileline/exile-agent/blob/main/app/api/v1/endpoints/agent.py"
click node_config_api "https://github.com/exileline/exile-agent/blob/main/app/api/v1/endpoints/ai_config.py"
click node_chat_service "https://github.com/exileline/exile-agent/blob/main/app/ai/services/chat_service.py"
click node_runtime_manager "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/manager.py"
click node_agent_registry "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/registry.py"
click node_agent_router "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/agent_router.py"
click node_runner "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/runner.py"
click node_history "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/history.py"
click node_approvals "https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/approvals.py"
click node_skills "https://github.com/exileline/exile-agent/blob/main/app/ai/skills/resolver.py"
click node_skill_registry "https://github.com/exileline/exile-agent/blob/main/app/ai/skills/registry.py"
click node_mcp_manager "https://github.com/exileline/exile-agent/blob/main/app/ai/mcp/manager.py"
click node_toolsets "https://github.com/exileline/exile-agent/tree/main/app/ai/toolsets"
click node_config_service "https://github.com/exileline/exile-agent/blob/main/app/ai/services/config_admin_service.py"
click node_capability_resolver "https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/resolver.py"
click node_config_repository "https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/repository.py"
click node_config_models "https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/models.py"
click node_secret_encryption "https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/encryption.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_agent_api,node_config_api toneBlue
class node_chat_service,node_runtime_manager,node_agent_registry,node_agent_router,node_runner,node_database toneAmber
class node_history,node_approvals,node_skills,node_skill_registry,node_mcp_manager,node_toolsets,node_developer toneMint
class node_config_service,node_capability_resolver,node_config_repository,node_config_models,node_secret_encryption toneRose
class node_external_model toneIndigo
```

## Components

### HTTP API

- [Agent endpoints](https://github.com/exileline/exile-agent/blob/main/app/api/v1/endpoints/agent.py): `app/api/v1/endpoints/agent.py`
- [Config endpoints](https://github.com/exileline/exile-agent/blob/main/app/api/v1/endpoints/ai_config.py): `app/api/v1/endpoints/ai_config.py`

### Agent Runtime

- [Chat service](https://github.com/exileline/exile-agent/blob/main/app/ai/services/chat_service.py): `app/ai/services/chat_service.py`
- [Runtime manager](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/manager.py): `app/ai/runtime/manager.py`
- [Agent registry](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/registry.py): `app/ai/runtime/registry.py`
- [Agent router](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/agent_router.py): `app/ai/runtime/agent_router.py`
- [Run orchestrator](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/runner.py): `app/ai/runtime/runner.py`

### Runtime Capabilities

- [Session history](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/history.py): `app/ai/runtime/history.py`
- [Approval resume](https://github.com/exileline/exile-agent/blob/main/app/ai/runtime/approvals.py): `app/ai/runtime/approvals.py`
- [Skills injection](https://github.com/exileline/exile-agent/blob/main/app/ai/skills/resolver.py): `app/ai/skills/resolver.py`
- [Skill catalog](https://github.com/exileline/exile-agent/blob/main/app/ai/skills/registry.py): `app/ai/skills/registry.py`
- [MCP manager](https://github.com/exileline/exile-agent/blob/main/app/ai/mcp/manager.py): `app/ai/mcp/manager.py`
- [Tool governance](https://github.com/exileline/exile-agent/tree/main/app/ai/toolsets): `app/ai/toolsets`

### Configuration Control

- [Config admin](https://github.com/exileline/exile-agent/blob/main/app/ai/services/config_admin_service.py): `app/ai/services/config_admin_service.py`
- [Capability resolver](https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/resolver.py): `app/ai/config_store/resolver.py`
- [Config repository](https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/repository.py): `app/ai/config_store/repository.py`
- [Config records](https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/models.py): `app/ai/config_store/models.py`
- [Secret encryption](https://github.com/exileline/exile-agent/blob/main/app/ai/config_store/encryption.py): `app/ai/config_store/encryption.py`

### Other components

- **API caller**
- **Model provider**
- **SQL database**

## Connections

- API caller → Agent endpoints: submits chat
- Agent endpoints → Chat service: dispatches chat (evidence: `app/api/v1/endpoints/agent.py`)
- Chat service → Run orchestrator: runs request (evidence: `app/ai/services/chat_service.py`)
- Run orchestrator → Runtime manager: gets agent
- Runtime manager → Agent registry: builds agent (evidence: `app/ai/runtime/manager.py`)
- Run orchestrator → Agent router: routes request
- Run orchestrator → Session history: loads and saves
- Run orchestrator → Approval resume: pauses and resumes
- Run orchestrator → Skills injection: resolves skills
- Skills injection → Skill catalog: selects skills
- Run orchestrator → MCP manager: assembles MCP
- MCP manager → Tool governance: wraps toolsets (evidence: `app/ai/mcp/manager.py`)
- Run orchestrator → Model provider: invokes model
- API caller → Config endpoints: manages config
- Config endpoints → Config admin: delegates admin (evidence: `app/api/v1/endpoints/ai_config.py`)
- Config admin → Config repository: reads and writes (evidence: `app/ai/services/config_admin_service.py`)
- Config admin → Secret encryption: encrypts secrets (evidence: `app/ai/services/config_admin_service.py`)
- Config repository → Config records: persists records (evidence: `app/ai/config_store/repository.py`)
- Config repository → SQL database: queries database
- Capability resolver → Config repository: loads settings
- Run orchestrator → Capability resolver: resolves capabilities
