How langchain-ai/agent-protocol works
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.