76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# Gateway Architecture — Agent + Skill + Graph Pipeline
|
|
|
|
This is the **interface layer** of the Agents project. Everything that connects
|
|
the outside world to the agent system lives here — REST APIs, Discord bot,
|
|
and authentication.
|
|
|
|
---
|
|
|
|
## Directory Map
|
|
|
|
| Path | Description | Docs |
|
|
|---|---|---|
|
|
| `gateway/v1/` | REST API endpoints — chat, agent listing, OpenAI-compatible completions | [v1.md](v1/v1.md) |
|
|
| `gateway/discord/` | Discord bot connector — in-process DM handler with LangGraph integration | [discord.md](discord/discord.md) |
|
|
| `gateway/auth/` | Auth service registry + Jellyfin Quick Connect implementation | [auth.md](auth/auth.md) |
|
|
|
|
---
|
|
|
|
## Supporting Modules
|
|
|
|
| Path | Purpose |
|
|
|---|---|
|
|
| `gateway/dependencies.py` | FastAPI `Depends` providers — `get_llm_client()`, `get_agent_graph()` |
|
|
| `src/config.py` | `.env` loader and config accessor |
|
|
| `src/llm.py` | OpenAI-compatible client factory (DeepSeek) |
|
|
| `src/state.py` | LangGraph `AgentState` TypedDict |
|
|
| `src/graph.py` | LangGraph StateGraph factory — agent_node, tool_node, routing |
|
|
| `src/tools_adapter.py` | Wraps skill tools as LangChain `@tool` functions |
|
|
| `src/auth_store.py` | SQLite persistence for Discord → service auth linking |
|
|
| `agents/` | Agent definitions (dataclass + registry) |
|
|
| `agents/skills/` | Skill definitions — prompt fragments, tool schemas, executors |
|
|
|
|
---
|
|
|
|
## High-Level Request Flow
|
|
|
|
```
|
|
┌──────────────────────────────┐
|
|
│ Client (OpenWebUI / HTTP) │
|
|
└──────────────┬───────────────┘
|
|
│ POST /v1/chat/completions
|
|
▼
|
|
┌──────────────────────────────┐
|
|
│ gateway/v1/chat.py │ ← resolves agent, invokes graph
|
|
└──────────────┬───────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────┐
|
|
│ LangGraph StateGraph │ ← src/graph.py
|
|
│ ┌──────────┐ ┌──────────┐│
|
|
│ │agent_node│──▶│tool_node ││
|
|
│ │(LLM call)│◀──│(skills) ││
|
|
│ └──────────┘ └──────────┘│
|
|
└──────────────┬───────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────┐
|
|
│ agents/skills/ │ ← Seerr API, Jellyfin API, etc.
|
|
└──────────────────────────────┘
|
|
```
|
|
|
|
For a detailed step-by-step walkthrough of the graph execution (including
|
|
multi-turn context and tool-calling loops), see [v1.md](v1/v1.md).
|
|
|
|
---
|
|
|
|
## Startup
|
|
|
|
`main.py` is the entry point. At startup it:
|
|
|
|
1. Loads `.env` → creates the LLM client (DeepSeek) → stores on `app.state.llm_client`
|
|
2. Calls `load_all_agents()` → imports every agent and skill module (they self-register)
|
|
3. Imports `gateway.auth.jellyfin` → self-registers the Jellyfin auth service
|
|
4. Mounts routers: `/v1/*` (chat endpoints) and `/api/v1/auth/*` (auth endpoints)
|
|
5. Starts the Discord bot as a background asyncio task (lifespan)
|