Usage Guide

Setup and Usage

  1. Clone the repository:

    git clone https://github.com/kryvokhyzha/langgraph-agent-toolkit
cd langgraph-agent-toolkit

  2. Set up your environment (see Environment Setup section)

  3. Run the service (with Python or Docker)

Building Your Own Agent

To customize the agent:

  1. Add your agent to langgraph_agent_toolkit/agents/blueprints/

  2. Register it in AGENT_PATHS list in langgraph_agent_toolkit/core/settings.py

  3. Optionally customize the Streamlit interface in streamlit_app.py

Docker Setup

The docker-compose.yaml defines these services with enhanced security:

  • backend-agent-service: FastAPI service

  • frontend-streamlit-app: Streamlit chat interface

  • postgres: Database storage

  • redis: Cache and message broker

  • minio: Object storage

  • clickhouse: Analytics database

  • langfuse-web & langfuse-worker: Observability

  • litellm: LLM proxy server

Using docker compose watch enables live reloading:

  1. Ensure Docker and Docker Compose (>=2.23.0) are installed

  2. Launch services:

    docker compose watch

  3. Access endpoints:

    • Streamlit app: http://0.0.0.0:8501

    • Agent API: http://0.0.0.0:8080

    • API docs: http://0.0.0.0:8080/docs

    • Langfuse dashboard: http://0.0.0.0:3000

    • LiteLLM API: http://0.0.0.0:4000 (accessible from any host)

  4. Stop services:

    docker compose down

Note

If you modify pyproject.toml or uv.lock, rebuild with docker compose up --build

Using the AgentClient

The toolkit includes AgentClient for interacting with the agent service:

from client import AgentClient
client = AgentClient()

response = client.invoke({"message": "Tell me a brief joke?"})
response.pretty_print()
# ================================== Ai Message ==================================
#
# A man walked into a library and asked the librarian, "Do you have any books on Pavlov's dogs and Schrödinger's cat?"
# The librarian replied, "It rings a bell, but I'm not sure if it's here or not."

See langgraph_agent_toolkit/run_client.py for more examples.

Development with LangGraph Studio

The project works with LangGraph Studio:

  1. Install LangGraph Studio

  2. Add your .env file to the root directory

  3. Launch LangGraph Studio pointing at the project root

  4. Customize langgraph.json as needed

Local Development Without Docker

  1. Set up a Python environment:

    pip install uv
uv sync --frozen
source .venv/bin/activate

  2. Create and configure your .env file

  3. Run the FastAPI server:

    python langgraph_agent_toolkit/run_service.py

  4. Run the Streamlit app in another terminal:

    streamlit run langgraph_agent_toolkit/streamlit_app.py

  5. Access the Streamlit interface (usually at http://localhost:8501)

Key Features

LangGraph Integration

  • Latest LangGraph v0.3 features

  • Human-in-the-loop with interrupt()

  • Flow control with Command and langgraph-supervisor

API Service

  • FastAPI with streaming and non-streaming endpoints

  • Support for both token-based and message-based streaming

  • Multiple agent support with URL path routing

  • Available agents and models listed at /info endpoint

  • Supports different runners: unicorn, gunicorn, mangum (AWS Lambda), azure functions

Developer Experience

  • Asynchronous design with async/await

  • Docker configuration with live reloading

  • Comprehensive testing suite

Enterprise Components

  • Configurable PostgreSQL/SQLite connection pools

  • Observability via Langfuse and Langsmith

  • User feedback system

  • Prompt management system

  • LiteLLM proxy integration