agent-service-toolkit

A full toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit.

It includes a LangGraph agent, a FastAPI service to serve it, a client to interact with the service, and a Streamlit app that uses the client to provide a chat interface. Data structures and settings are built with Pydantic.

This project offers a template for you to easily build and run your own agents using the LangGraph framework. It demonstrates a complete setup from agent definition to user interface, making it easier to get started with LangGraph-based projects by providing a full, robust toolkit.

🎥 Watch a video walkthrough of the repo and app

Overview

Try the app!

Quickstart

Run directly in python

# At least one LLM API key is required
echo 'OPENAI_API_KEY=your_openai_api_key' >> .env

# uv is the recommended way to install agent-service-toolkit, but "pip install ." also works
# For uv installation options, see: https://docs.astral.sh/uv/getting-started/installation/
curl -LsSf https://astral.sh/uv/0.11.26/install.sh | sh

# Install dependencies. "uv sync" creates .venv automatically
uv sync --frozen
source .venv/bin/activate
python src/run_service.py

# In another shell
source .venv/bin/activate
streamlit run src/streamlit_app.py

Run with docker

echo 'OPENAI_API_KEY=your_openai_api_key' >> .env
docker compose watch

Architecture Diagram

Key Features

1. LangGraph Agent and latest features: A customizable agent built using the LangGraph framework. Implements the latest LangGraph v1.0 features including human in the loop with interrupt(), flow control with Command, long-term memory with Store, and langgraph-supervisor.
2. FastAPI Service: Serves the agent with both streaming and non-streaming endpoints.
3. Advanced Streaming: A novel approach to support both token-based and message-based streaming.
4. AG-UI Protocol Support: Every agent is also served over the AG-UI protocol for connecting AG-UI compatible frontends like CopilotKit - see docs.
5. Streamlit Interface: Provides a user-friendly chat interface for interacting with the agent, including voice input and output.
6. Multiple Agent Support: Run multiple agents in the service and call by URL path. Available agents and models are described in /info
7. Asynchronous Design: Utilizes async/await for efficient handling of concurrent requests.
8. Content Moderation: Implements Safeguard for content moderation (requires Groq API key).
9. RAG Agent: A basic RAG agent implementation using ChromaDB - see docs.
10. Feedback Mechanism: Includes a star-based feedback system integrated with LangSmith.
11. Docker Support: Includes Dockerfiles and a docker compose file for easy development and deployment.
12. Testing: Includes robust unit and integration tests for the full repo.

Key Files

The repository is structured as follows:

• src/agents/: Defines several agents with different capabilities
• src/schema/: Defines the protocol schema
• src/core/: Core modules including LLM definition and settings
• src/service/service.py: FastAPI service to serve the agents
• src/client/client.py: Client to interact with the agent service
• src/streamlit_app.py: Streamlit app providing a chat interface
• tests/: Unit and integration tests

Setup and Usage

1. Clone the repository:

   git clone https://github.com/JoshuaC215/agent-service-toolkit.git
   cd agent-service-toolkit
   

2. Set up environment variables: Create a .env file in the root directory. At least one LLM API key or configuration is required. See the .env.example file for a full list of available environment variables, including a variety of model provider API keys, header-based authentication, LangSmith tracing, testing and development modes, and OpenWeatherMap API key.

3. You can now run the agent service and the Streamlit app locally, either with Docker or just using Python. The Docker setup is recommended for simpler environment setup and immediate reloading of the services when you make changes to your code.

Additional setup for specific AI providers

• Setting up Ollama
• Setting up VertexAI
• Setting up RAG with ChromaDB

Building or customizing your own agent

To customize the agent for your own use case:

1. Add your new agent to the src/agents directory. You can copy research_assistant.py or chatbot.py and modify it to change the agent's behavior and tools.
2. Import and add your new agent to the agents dictionary in src/agents/agents.py. Your agent can be called by /<your_agent_name>/invoke or /<your_agent_name>/stream.
3. Adjust the Streamlit interface in src/streamlit_app.py to match your agent's capabilities.

Handling Private Credential files

If your agents or chosen LLM require file-based credential files or certificates, the privatecredentials/ has been provided for your development convenience. All contents, excluding the .gitkeep files, are ignored by git and docker's build process. See Working with File-based Credentials for suggested use.

Docker Setup

This project includes a Docker setup for easy development and deployment. The compose.yaml file defines three services: postgres, agent_service and streamlit_app. The Dockerfile for each service is in their respective directories.

For local development, we recommend using docker compose watch. This feature allows for a smoother development experience by automatically updating your containers when changes are detected in your source code.

1. Make sure you have Docker and Docker Compose (>= v2.23.0) installed on your system.

2. Create a .env file from the .env.example. At minimum, you need to provide an LLM API key (e.g., OPENAI_API_KEY).

   cp .env.example .env
   # Edit .env to add your API keys
   

3. Build and launch the services in watch mode:

   docker compose watch
   

   This will automatically:

   • Start a PostgreSQL database service that the agent service connects to
   • Start the agent service with FastAPI
   • Start the Streamlit app for the user interface

4. The services will now automatically update when you make changes to your code:

   • Changes in the relevant python files and directories will trigger updates for the relevant services.
   • NOTE: If you make changes to the pyproject.toml or uv.lock files, you will need to rebuild the services by running docker compose up --build.

5. Access the Streamlit app by navigating to http://localhost:8501 in your web browser.

6. The agent service API will be available at http://0.0.0.0:8080. You can also use the OpenAPI docs at http://0.0.0.0:8080/redoc.

7. Use docker compose down to stop the services.

This setup allows you to develop and test your changes in real-time without manually restarting the services.

Building other apps on the AgentClient

The repo includes a generic src/client/client.AgentClient that can be used to interact with the agent service. This client is designed to be flexible and can be used to build other apps on top of the agent. It supports both synchronous and asynchronous invocations, and streaming and non-streaming requests.

See the src/run_client.py file for full examples of how to use the AgentClient. A quick example:

from client import AgentClient
client = AgentClient()

response = client.invoke("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."

Development with LangGraph Studio

The agent supports LangGraph Studio, the IDE for developing agents in LangGraph.

langgraph-cli[inmem] is installed with uv sync. You can simply add your .env file to the root directory as described above, and then launch LangGraph Studio with langgraph dev. Customize langgraph.json as needed. See the local quickstart to learn more.

Local development without Docker

You can also run the agent service and the Streamlit app locally without Docker, just using a Python virtual environment.

1. Create a virtual environment and install dependencies:

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

2. Run the FastAPI server:

   python src/run_service.py
   

3. In a separate terminal, run the Streamlit app:

   streamlit run src/streamlit_app.py
   

4. Open your browser and navigate to the URL provided by Streamlit (usually http://localhost:8501).

Projects built with or inspired by agent-service-toolkit

The following are a few of the public projects that drew code or inspiration from this repo.

• PolyRAG - Extends agent-service-toolkit with RAG capabilities over both PostgreSQL databases and PDF documents.
• alexrisch/agent-web-kit - A Next.JS frontend for agent-service-toolkit
• raushan-in/dapa - Digital Arrest Protection App (DAPA) enables users to report financial scams and frauds efficiently via a user-friendly platform.

Please create a pull request editing the README or open a discussion with any new ones to be added! Would love to include more projects.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Currently the tests need to be run using the local development without Docker setup. To run the tests for the agent service:

1. Ensure you're in the project root directory and have activated your virtual environment.

2. Install the development dependencies and pre-commit hooks:

   uv sync --frozen
   pre-commit install
   

3. Run the tests using pytest:

   pytest
   

Smoke testing optional dependencies

Some integrations aren't exercised by the unit suite or the default CI run because they need real infrastructure: the Postgres and MongoDB checkpointers, the AG-UI endpoint, and LangFuse tracing. scripts/smoke_test.sh spins up each dependency in Docker, runs the service against it, verifies the integration end-to-end (including a check that the intended backend was actually used, not a silent SQLite fallback), and tears it down.

./scripts/smoke_test.sh                 # default: postgres, mongo, agui
./scripts/smoke_test.sh mongo           # a single target
./scripts/smoke_test.sh langfuse        # heavy: starts LangFuse's full self-host stack
./scripts/smoke_test.sh all             # everything, including langfuse

These are opt-in confidence checks for a maintainer or agent — not part of CI. Run the target that matches what you changed rather than the whole set. The optional add-on compose files live in docker/ (e.g. docker/compose.mongo.yaml), layered on top of the default compose.yaml so the default stack stays lightweight.

License

This project is licensed under the MIT License - see the LICENSE file for details.