[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72175":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":16,"starSnapshotCount":16,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},72175,"agent-service-toolkit","JoshuaC215\u002Fagent-service-toolkit","JoshuaC215","Full toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit","https:\u002F\u002Fagent-service-toolkit.streamlit.app",null,"Python",4325,720,39,18,0,11,29,71,33,102.17,"MIT License",false,"main",[26,27,28],"agents","langgraph","streamlit","2026-06-12 04:01:03","# 🧰 AI Agent Service Toolkit\n\n[![build status](https:\u002F\u002Fgithub.com\u002FJoshuaC215\u002Fagent-service-toolkit\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FJoshuaC215\u002Fagent-service-toolkit\u002Factions\u002Fworkflows\u002Ftest.yml) [![codecov](https:\u002F\u002Fcodecov.io\u002Fgithub\u002FJoshuaC215\u002Fagent-service-toolkit\u002Fgraph\u002Fbadge.svg?token=5MTJSYWD05)](https:\u002F\u002Fcodecov.io\u002Fgithub\u002FJoshuaC215\u002Fagent-service-toolkit) [![Python Version](https:\u002F\u002Fimg.shields.io\u002Fpython\u002Frequired-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FJoshuaC215%2Fagent-service-toolkit%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)](https:\u002F\u002Fgithub.com\u002FJoshuaC215\u002Fagent-service-toolkit\u002Fblob\u002Fmain\u002Fpyproject.toml)\n[![GitHub License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FJoshuaC215\u002Fagent-service-toolkit)](https:\u002F\u002Fgithub.com\u002FJoshuaC215\u002Fagent-service-toolkit\u002Fblob\u002Fmain\u002FLICENSE) [![Streamlit App](https:\u002F\u002Fstatic.streamlit.io\u002Fbadges\u002Fstreamlit_badge_black_red.svg)](https:\u002F\u002Fagent-service-toolkit.streamlit.app\u002F)\n\nA full toolkit for running an AI agent service built with LangGraph, FastAPI and Streamlit.\n\nIt includes a [LangGraph](https:\u002F\u002Flangchain-ai.github.io\u002Flanggraph\u002F) agent, a [FastAPI](https:\u002F\u002Ffastapi.tiangolo.com\u002F) service to serve it, a client to interact with the service, and a [Streamlit](https:\u002F\u002Fstreamlit.io\u002F) app that uses the client to provide a chat interface. Data structures and settings are built with [Pydantic](https:\u002F\u002Fgithub.com\u002Fpydantic\u002Fpydantic).\n\nThis 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.\n\n**[🎥 Watch a video walkthrough of the repo and app](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=pdYVHw_YCNY)**\n\n## Overview\n\n### [Try the app!](https:\u002F\u002Fagent-service-toolkit.streamlit.app\u002F)\n\n\u003Ca href=\"https:\u002F\u002Fagent-service-toolkit.streamlit.app\u002F\">\u003Cimg src=\"media\u002Fapp_screenshot.png\" width=\"600\">\u003C\u002Fa>\n\n### Quickstart\n\nRun directly in python\n\n```sh\n# At least one LLM API key is required\necho 'OPENAI_API_KEY=your_openai_api_key' >> .env\n\n# uv is the recommended way to install agent-service-toolkit, but \"pip install .\" also works\n# For uv installation options, see: https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002Fgetting-started\u002Finstallation\u002F\ncurl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002F0.7.19\u002Finstall.sh | sh\n\n# Install dependencies. \"uv sync\" creates .venv automatically\nuv sync --frozen\nsource .venv\u002Fbin\u002Factivate\npython src\u002Frun_service.py\n\n# In another shell\nsource .venv\u002Fbin\u002Factivate\nstreamlit run src\u002Fstreamlit_app.py\n```\n\nRun with docker\n\n```sh\necho 'OPENAI_API_KEY=your_openai_api_key' >> .env\ndocker compose watch\n```\n\n### Architecture Diagram\n\n\u003Cimg src=\"media\u002Fagent_architecture.png\" width=\"600\">\n\n### Key Features\n\n1. **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`.\n1. **FastAPI Service**: Serves the agent with both streaming and non-streaming endpoints.\n1. **Advanced Streaming**: A novel approach to support both token-based and message-based streaming.\n1. **Streamlit Interface**: Provides a user-friendly chat interface for interacting with the agent, including voice input and output.\n1. **Multiple Agent Support**: Run multiple agents in the service and call by URL path. Available agents and models are described in `\u002Finfo`\n1. **Asynchronous Design**: Utilizes async\u002Fawait for efficient handling of concurrent requests.\n1. **Content Moderation**: Implements Safeguard for content moderation (requires Groq API key).\n1. **RAG Agent**: A basic RAG agent implementation using ChromaDB - see [docs](docs\u002FRAG_Assistant.md).\n1. **Feedback Mechanism**: Includes a star-based feedback system integrated with LangSmith.\n1. **Docker Support**: Includes Dockerfiles and a docker compose file for easy development and deployment.\n1. **Testing**: Includes robust unit and integration tests for the full repo.\n\n### Key Files\n\nThe repository is structured as follows:\n\n- `src\u002Fagents\u002F`: Defines several agents with different capabilities\n- `src\u002Fschema\u002F`: Defines the protocol schema\n- `src\u002Fcore\u002F`: Core modules including LLM definition and settings\n- `src\u002Fservice\u002Fservice.py`: FastAPI service to serve the agents\n- `src\u002Fclient\u002Fclient.py`: Client to interact with the agent service\n- `src\u002Fstreamlit_app.py`: Streamlit app providing a chat interface\n- `tests\u002F`: Unit and integration tests\n\n## Setup and Usage\n\n1. Clone the repository:\n\n   ```sh\n   git clone https:\u002F\u002Fgithub.com\u002FJoshuaC215\u002Fagent-service-toolkit.git\n   cd agent-service-toolkit\n   ```\n\n2. Set up environment variables:\n   Create a `.env` file in the root directory. At least one LLM API key or configuration is required. See the [`.env.example` file](.\u002F.env.example) 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.\n\n3. 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.\n\n### Additional setup for specific AI providers\n\n- [Setting up Ollama](docs\u002FOllama.md)\n- [Setting up VertexAI](docs\u002FVertexAI.md)\n- [Setting up RAG with ChromaDB](docs\u002FRAG_Assistant.md)\n\n### Building or customizing your own agent\n\nTo customize the agent for your own use case:\n\n1. Add your new agent to the `src\u002Fagents` directory. You can copy `research_assistant.py` or `chatbot.py` and modify it to change the agent's behavior and tools.\n1. Import and add your new agent to the `agents` dictionary in `src\u002Fagents\u002Fagents.py`. Your agent can be called by `\u002F\u003Cyour_agent_name>\u002Finvoke` or `\u002F\u003Cyour_agent_name>\u002Fstream`.\n1. Adjust the Streamlit interface in `src\u002Fstreamlit_app.py` to match your agent's capabilities.\n\n\n### Handling Private Credential files\n\nIf your agents or chosen LLM require file-based credential files or certificates, the `privatecredentials\u002F` 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](docs\u002FFile_Based_Credentials.md) for suggested use.\n\n\n### Docker Setup\n\nThis 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.\n\nFor local development, we recommend using [docker compose watch](https:\u002F\u002Fdocs.docker.com\u002Fcompose\u002Ffile-watch\u002F). This feature allows for a smoother development experience by automatically updating your containers when changes are detected in your source code.\n\n1. Make sure you have Docker and Docker Compose (>= [v2.23.0](https:\u002F\u002Fdocs.docker.com\u002Fcompose\u002Frelease-notes\u002F#2230)) installed on your system.\n\n2. Create a `.env` file from the `.env.example`. At minimum, you need to provide an LLM API key (e.g., OPENAI_API_KEY).\n   ```sh\n   cp .env.example .env\n   # Edit .env to add your API keys\n   ```\n\n3. Build and launch the services in watch mode:\n\n   ```sh\n   docker compose watch\n   ```\n\n   This will automatically:\n   - Start a PostgreSQL database service that the agent service connects to\n   - Start the agent service with FastAPI\n   - Start the Streamlit app for the user interface\n\n4. The services will now automatically update when you make changes to your code:\n   - Changes in the relevant python files and directories will trigger updates for the relevant services.\n   - 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`.\n\n5. Access the Streamlit app by navigating to `http:\u002F\u002Flocalhost:8501` in your web browser.\n\n6. The agent service API will be available at `http:\u002F\u002F0.0.0.0:8080`. You can also use the OpenAPI docs at `http:\u002F\u002F0.0.0.0:8080\u002Fredoc`.\n\n7. Use `docker compose down` to stop the services.\n\nThis setup allows you to develop and test your changes in real-time without manually restarting the services.\n\n### Building other apps on the AgentClient\n\nThe repo includes a generic `src\u002Fclient\u002Fclient.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.\n\nSee the `src\u002Frun_client.py` file for full examples of how to use the `AgentClient`. A quick example:\n\n```python\nfrom client import AgentClient\nclient = AgentClient()\n\nresponse = client.invoke(\"Tell me a brief joke?\")\nresponse.pretty_print()\n# ================================== Ai Message ==================================\n#\n# A man walked into a library and asked the librarian, \"Do you have any books on Pavlov's dogs and Schrödinger's cat?\"\n# The librarian replied, \"It rings a bell, but I'm not sure if it's here or not.\"\n\n```\n\n### Development with LangGraph Studio\n\nThe agent supports [LangGraph Studio](https:\u002F\u002Flangchain-ai.github.io\u002Flanggraph\u002Fconcepts\u002Flanggraph_studio\u002F), the IDE for developing agents in LangGraph.\n\n`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](https:\u002F\u002Flangchain-ai.github.io\u002Flanggraph\u002Fcloud\u002Fhow-tos\u002Fstudio\u002Fquick_start\u002F#local-development-server) to learn more.\n\n### Local development without Docker\n\nYou can also run the agent service and the Streamlit app locally without Docker, just using a Python virtual environment.\n\n1. Create a virtual environment and install dependencies:\n\n   ```sh\n   uv sync --frozen\n   source .venv\u002Fbin\u002Factivate\n   ```\n\n2. Run the FastAPI server:\n\n   ```sh\n   python src\u002Frun_service.py\n   ```\n\n3. In a separate terminal, run the Streamlit app:\n\n   ```sh\n   streamlit run src\u002Fstreamlit_app.py\n   ```\n\n4. Open your browser and navigate to the URL provided by Streamlit (usually `http:\u002F\u002Flocalhost:8501`).\n\n## Projects built with or inspired by agent-service-toolkit\n\nThe following are a few of the public projects that drew code or inspiration from this repo.\n\n- **[PolyRAG](https:\u002F\u002Fgithub.com\u002FQuentinFuxa\u002FPolyRAG)** - Extends agent-service-toolkit with RAG capabilities over both PostgreSQL databases and PDF documents.\n- **[alexrisch\u002Fagent-web-kit](https:\u002F\u002Fgithub.com\u002Falexrisch\u002Fagent-web-kit)** - A Next.JS frontend for agent-service-toolkit\n- **[raushan-in\u002Fdapa](https:\u002F\u002Fgithub.com\u002Fraushan-in\u002Fdapa)** - Digital Arrest Protection App (DAPA) enables users to report financial scams and frauds efficiently via a user-friendly platform.\n\n**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.\n\n## Contributing\n\nContributions 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:\n\n1. Ensure you're in the project root directory and have activated your virtual environment.\n\n2. Install the development dependencies and pre-commit hooks:\n\n   ```sh\n   uv sync --frozen\n   pre-commit install\n   ```\n\n3. Run the tests using pytest:\n\n   ```sh\n   pytest\n   ```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","AI Agent Service Toolkit 是一个用于构建和运行基于LangGraph框架的AI代理服务的完整工具包。它利用了FastAPI来提供后端服务，Streamlit来创建前端交互界面，并且使用Pydantic定义数据结构与配置。此项目集成了最新的LangGraph特性如中断处理和支持流控制等，使得开发者能够轻松地定制自己的AI代理。非常适合需要快速搭建具有对话功能的AI应用场景，比如客户服务自动化、虚拟助手开发等领域。",2,"2026-06-11 03:40:43","high_star"]