# langchain-ai/agent-protocol architecture

> Architecture diagram of the GitHub repository langchain-ai/agent-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langchain-ai/agent-protocol
- Repository: https://github.com/langchain-ai/agent-protocol

## Overview

##### Project Type & Purpose
- This project is a Python-based backend server that implements the Agent Protocol. The protocol is designed to handle interactions for LLM agents in production by defining a set of framework-agnostic RESTful API endpoints.
- Its purpose is to provide endpoints for managing agent executions (“runs”), multi-turn conversation threads, stateless interactions, long-term memory storage (store), and agent introspection. The system is built with FastAPI (using Pydantic V2 for data models) and follows a modular design via separate routers.

##### File Structure
- At the top level, you see documentation files (README.md, api.html, openapi.json, etc.) and licensing/contributing guidelines.
- The “server” directory contains the core of the application:
- The folder “ap_server” holds the main application files:
- main.py: The entry point for running the server.
- models.py: Pydantic models for validating incoming and outgoing data.
- The “routers” subdirectory contains separate files for each API segment:
▪ agents.py – Handles introspection endpoints.
▪ runs.py – Implements endpoints for agent “runs” (both fire-and-forget and blocking patterns).
▪ stateless_runs.py – Manages one-shot, ephemeral runs.
▪ store.py – Provides endpoints for long-term memory operations.
▪ threads.py – Handles multi-turn conversation threads.
- The “tooling” directory suggests scripts and configuration (e.g., Makefile, pyproject.toml) that help build, test, or deploy the project.

##### Main Components
a. External Client(s): Represent API consumers such as LLM agent callers (e.g., LangGraph Platform or community implementations) initiating HTTP requests.
b. API Gateway / Server Instance: The core “Agent Protocol Server” that accepts and processes incoming requests.
c. Routers/Modules within the Server:
- Agents Module: Handles endpoints for agent introspection (discovering agent capabilities and schemas).
- Threads Module: Manages creation, retrieval, updating, and deletion of multi-turn interaction threads.
- Runs Module: Manages “run” operations, including both asynchronous/background and blocking executions.
- Stateless Runs Module: Facilitates one-shot interactions where a thread is created and deleted automatically.
- Store Module: Provides CRUD operations for long-term memory items (for example, user profiles or context storage).
d. Documentation / Specification: Although not part of runtime, include a component referencing the OpenAPI JSON spec and API HTML docs (api.html, openapi.json) as they form the contract for the API.

##### Relationships & Data Flow
- From the API Gateway (the FastAPI server), illustrate the request routing into the various modules (agents, threads, runs/stateless_runs, store).
- Within each module, show internal handling where data validation (via Pydantic models) leads to CRUD or execution actions.
- Data storage or temporary runtime states (such as in-memory execution queues for runs and state logs for threads). Even if there isn’t a separate database explicitly shown in the file tree, the conceptual model of state management is intrinsic to the protocol.

##### Architectural Patterns & Design Principles
- Modularization: Each API segment is implemented as a separate router making the system decoupled and easier to extend.
- API-First Design: The presence of the OpenAPI spec (openapi.json) indicates an API-first approach, ensuring that clients and server adhere to predefined contracts.
- RESTful Endpoints: Clear separation of concerns across the endpoints, with distinct actions for runs, threads, stores, and agents.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["External Client (LLM Agent Caller)"]:::external
    API["API Gateway (FastAPI Server)"]:::server
    DataModels["Data Models/Validation (models.py)"]:::model

    subgraph "Routers"
        Agents["Router: Agents"]:::router
        Runs["Router: Runs"]:::router
        Stateless["Router: Stateless Runs"]:::router
        Store["Router: Store"]:::router
        Threads["Router: Threads"]:::router
    end

    subgraph "Documentation"
        API_HTML["API HTML Docs"]:::doc
        OpenAPI["OpenAPI Spec (openapi.json)"]:::doc
    end

    Client -->|"request"| API
    API -->|"validate"| DataModels
    API -->|"routes_to"| Agents
    API -->|"routes_to"| Runs
    API -->|"routes_to"| Stateless
    API -->|"routes_to"| Store
    API -->|"routes_to"| Threads
    API -->|"exposes"| API_HTML
    API -->|"exposes"| OpenAPI

    click API "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/main.py"
    click DataModels "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/models.py"
    click Agents "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/routers/agents.py"
    click Runs "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/routers/runs.py"
    click Stateless "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/routers/stateless_runs.py"
    click Store "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/routers/store.py"
    click Threads "https://github.com/langchain-ai/agent-protocol/blob/main/server/ap_server/routers/threads.py"
    click API_HTML "https://github.com/langchain-ai/agent-protocol/blob/main/api.html"
    click OpenAPI "https://github.com/langchain-ai/agent-protocol/blob/main/openapi.json"

    classDef external fill:#fef2cc,stroke:#e4b400,stroke-width:2px;
    classDef server fill:#cce5ff,stroke:#339af0,stroke-width:2px;
    classDef router fill:#d1e7dd,stroke:#198754,stroke-width:2px;
    classDef model fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef doc fill:#e2e3e5,stroke:#adb5bd,stroke-width:2px;
```
