AI代理服务工具包

Install dependencies. "uv sync" creates .venv automatically

uv sync --frozen source .venv/bin/activate python src/run_service.py

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.7.19/install.sh | sh

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.

1. 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.

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
   

1. 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.

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

1. 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.

1. 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:

```python from client import AgentClient client = AgentClient()

response = client.invoke("Tell me a brief joke?") response.pretty_print()

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
   

1. Run the FastAPI server:

   python src/run_service.py
   

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

   streamlit run src/streamlit_app.py
   

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

Quickstart

Run directly in python

```sh

At least one LLM API key is required

echo 'OPENAI_API_KEY=your_openai_api_key' >> .env