Agents/gateway/api.md

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
gateway/discord/	Discord bot connector — in-process DM handler with LangGraph integration	discord.md
gateway/auth/	Auth service registry + Jellyfin Quick Connect implementation	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.

---

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)