Skip to content

Commit ff9b19e

Browse files
Rook1exjasinluo
Rook1ex
and
jasinluo
authored
docs: add INSTALL.md (#29)
Co-authored-by: jasinluo <jasinluo@tencent.com>
1 parent 72f66ae commit ff9b19e

2 files changed

Lines changed: 634 additions & 0 deletions

File tree

‎INSTALL.md‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
# Installation Guide
2+
3+
## Overview
4+
5+
| Item | Details |
6+
| ---------- | -------------------------------------------------------------------- |
7+
| Name | tRPC-Agent-Python (`trpc-agent-py`) |
8+
| Version | **0.1.0** |
9+
| Description | A production-grade agent framework developed by Tencent, supporting multiple model providers (including OpenAI, Anthropic, DeepSeek, and LiteLLM). It provides tool-calling capabilities, multi-agent orchestration, session and long-term memory management, RAG-based knowledge, and seamless deployment as a service via FastAPI. |
10+
| License | Apache-2.0 |
11+
| Repository | https://github.com/trpc-group/trpc-agent-python |
12+
13+
## Platforms
14+
15+
| Operating System | Support Status |
16+
| -------------------------- | -------------- |
17+
| Linux (Ubuntu/CentOS/Debian) | ✅ Fully supported (recommended for production) |
18+
| macOS (Intel / Apple Silicon) | ✅ Fully supported (recommended for development) |
19+
20+
---
21+
22+
## Dependencies
23+
24+
### Required Dependencies
25+
26+
| Dependency | Version | Description | Download URL |
27+
| ------------- | -------------- | --------------------------------- | ------------------------------------------------ |
28+
| **Python** | 3.12 | Runtime environment | https://www.python.org/downloads/ |
29+
| **pip** | >= 21.0 | Python package manager | Bundled with Python, upgrade via `pip install --upgrade pip` |
30+
| **git** | >= 2.0 | Required for source code installation | https://git-scm.com/downloads |
31+
32+
### Core Dependencies
33+
34+
The core dependencies are `automatically installed` when installing `trpc-agent-py`, the complete list of core dependencies please refer to `requirements.txt` ([./requirements.txt](./requirements.txt)) file.
35+
36+
### Optional Dependencies
37+
38+
| Dependency | Purpose | Installation |
39+
| ------------- | --------------------------------- | ----------------------------------------------- |
40+
| **Docker** | CodeExecutor containerized execution | https://docs.docker.com/get-docker/ |
41+
| **Redis** | Redis session/memory | https://redis.io/download |
42+
| **MySQL** | SQL session | https://dev.mysql.com/downloads/ |
43+
44+
45+
> **Tip**: It is recommended to use [pyenv](https://github.com/pyenv/pyenv) or [conda](https://docs.conda.io/) to manage Python versions and avoid conflicts with the system Python.
46+
47+
---
48+
49+
## Installation
50+
51+
### Pip Installation
52+
53+
```bash
54+
# Create a virtual environment
55+
python3 -m venv .venv
56+
57+
# Activate the virtual environment
58+
source .venv/bin/activate # Linux / macOS
59+
# .venv\Scripts\activate # Windows
60+
61+
pip install trpc-agent-py
62+
```
63+
64+
Install optional extensions:
65+
66+
```bash
67+
# Choose as needed, multiple extensions can be combined with commas
68+
pip install "trpc-agent-py[a2a,knowledge,agent-claude]"
69+
```
70+
71+
---
72+
73+
### Source Code Installation
74+
75+
```bash
76+
# Clone the repository
77+
git clone https://github.com/trpc-group/trpc-agent-python.git
78+
cd trpc-agent-python
79+
# Create and activate a virtual environment
80+
python3 -m venv .venv
81+
source .venv/bin/activate # Linux / macOS
82+
# .venv\Scripts\activate # Windows
83+
# Install
84+
pip install -e .
85+
```
86+
87+
### Optional Dependencies Reference
88+
89+
| Extension | Purpose | Key Dependencies | Install Command |
90+
| ---------------- | ----------------------------- | -------------------------------------------- | --------------------------------------- |
91+
| `a2a` | Google A2A protocol | a2a-sdk, protobuf | `pip install "trpc-agent-py[a2a]"` |
92+
| `ag-ui` | AG-UI protocol | ag-ui-protocol | `pip install "trpc-agent-py[ag-ui]"` |
93+
| `agent-claude` | Claude Agent | claude-agent-sdk, cloudpickle | `pip install "trpc-agent-py[agent-claude]"` |
94+
| `knowledge` | Knowledge base / RAG | numpy, langchain_community, langchain_huggingface | `pip install "trpc-agent-py[knowledge]"` |
95+
| `mem0` | Long-term memory (Mem0) | mem0ai, sentence-transformers | `pip install "trpc-agent-py[mem0]"` |
96+
| `langchain_tool` | LangChain Tool integration | langchain_tavily | `pip install "trpc-agent-py[langchain_tool]"` |
97+
| `langfuse` | Langfuse observability | opentelemetry-sdk, opentelemetry-exporter | `pip install "trpc-agent-py[langfuse]"` |
98+
| `eval` | Evaluation framework | pytest, rouge-score, pandas, tabulate | `pip install "trpc-agent-py[eval]"` |
99+
| `openclaw` | OpenClaw integration | nanobot-ai, wecom-aibot-sdk-python | `pip install "trpc-agent-py[openclaw]"` |
100+
| `dev` | Development (lint/format/test)| yapf, flake8, pytest, pytest-asyncio | `pip install "trpc-agent-py[dev]"` |
101+
| `all` | All optional dependencies | All of the above | `pip install "trpc-agent-py[all]"` |
102+
103+
---
104+
105+
## Configuration
106+
107+
### Environment Variables
108+
109+
trpc-agent-py uses environment variables to configure model connections. There are two ways to set them:
110+
111+
**Option 1**: Create a `.env` file in the project directory (recommended)
112+
113+
```bash
114+
# .env file contents
115+
# Model API key
116+
TRPC_AGENT_API_KEY="your-api-key"
117+
118+
# Model service URL
119+
TRPC_AGENT_BASE_URL="your-base-url"
120+
121+
# Default model name
122+
TRPC_AGENT_MODEL_NAME="your-model-name"
123+
```
124+
125+
> **Note**: Do not commit the `.env` file to version control. Make sure `.gitignore` includes `.env`.
126+
127+
**Option 2**: Export directly to the shell environment
128+
129+
```bash
130+
export TRPC_AGENT_API_KEY="your-api-key"
131+
export TRPC_AGENT_BASE_URL="your-base-url"
132+
export TRPC_AGENT_MODEL_NAME="your-model-name"
133+
```
134+
135+
### Configuration File Locations
136+
137+
| File | Location | Description |
138+
| ----------------- | --------- | ----------------------------------- |
139+
| `.env` | Project root / example subdirectories | Environment variable config (templates available in each example directory) |
140+
| `pyproject.toml` | Project root | Build config, tool config (yapf/pytest, etc.) |
141+
142+
---
143+
144+
## Verification
145+
146+
### Check Framework Version
147+
148+
```bash
149+
python -c "from trpc_agent_sdk.version import __version__; print(f'trpc-agent-py {__version__}')"
150+
```
151+
152+
### Check Core Module Imports
153+
154+
```bash
155+
python -c "
156+
from trpc_agent_sdk.agents import LlmAgent, ChainAgent, ParallelAgent, TransferAgent
157+
from trpc_agent_sdk.runners import Runner
158+
from trpc_agent_sdk.sessions import InMemorySessionService
159+
from trpc_agent_sdk.tools import FunctionTool
160+
from trpc_agent_sdk.models import OpenAIModel
161+
print('All core modules imported successfully.')
162+
"
163+
```
164+
165+
Expected output:
166+
```
167+
All core modules imported successfully.
168+
```
169+
### Run Unit Tests
170+
171+
```bash
172+
# Install test dependencies
173+
pip install -r requirements-test.txt
174+
# Run all tests
175+
pytest tests/ -v
176+
```
177+
178+
## Troubleshooting
179+
180+
### Pip install is slow or times out
181+
182+
**Problem**: Installation hangs or reports `ReadTimeoutError`.
183+
184+
**Solution**: Use a mirror to speed up downloads.
185+
186+
```bash
187+
# Temporary usage Tencent Cloud mirror
188+
pip install trpc-agent-py -i https://mirrors.cloud.tencent.com/pypi/simple
189+
190+
# Set global Tencent Cloud mirror
191+
pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple
192+
```
193+
194+
Other available mirrors:
195+
| Mirror | URL |
196+
| -------- | ------------------------------------------- |
197+
| Tencent Cloud | https://mirrors.cloud.tencent.com/pypi/simple |
198+
| Tsinghua | https://pypi.tuna.tsinghua.edu.cn/simple |
199+
| Alibaba Cloud | https://mirrors.aliyun.com/pypi/simple/ |
200+
201+
---
202+
203+
### Python version does not meet requirements
204+
205+
**Problem**:
206+
```
207+
ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10'
208+
```
209+
210+
**Solution**: Upgrade to Python 3.12.
211+
212+
```bash
213+
# Solution 1: Using pyenv to install Python 3.12
214+
pyenv install 3.12
215+
pyenv local 3.12
216+
217+
# Solution 2: Using conda to create a virtual environment and activate it
218+
conda create -n trpc-agent-py python=3.12
219+
conda activate trpc-agent-py
220+
```
221+
222+
Verify the version:
223+
```bash
224+
python3 --version
225+
```
226+
227+
---
228+
229+
### Permission denied
230+
231+
**Problem**:
232+
```
233+
ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied
234+
```
235+
236+
**Solution**:
237+
238+
```bash
239+
# Recommended: use a virtual environment to avoid permission issues
240+
python3 -m venv .venv
241+
source .venv/bin/activate
242+
pip install trpc-agent-py
243+
```
244+
245+
> **Note**: It is not recommended to use `sudo pip install` as it may corrupt the system Python environment.
246+
247+
---
248+
249+
### Model call error: TRPC_AGENT_API_KEY must be set
250+
251+
**Problem**: Reports that the API key is not set or is empty.
252+
253+
**Solution**:
254+
255+
```bash
256+
# Check if the environment variable is set
257+
echo $TRPC_AGENT_API_KEY
258+
259+
# If empty, set the environment variables
260+
export TRPC_AGENT_API_KEY="your-api-key"
261+
export TRPC_AGENT_BASE_URL="your-base-url"
262+
export TRPC_AGENT_MODEL_NAME="your-model-name"
263+
```
264+
265+
If using a `.env` file, make sure dotenv is loaded in your code:
266+
```python
267+
from dotenv import load_dotenv
268+
load_dotenv()
269+
```
270+
271+
---
272+
273+
### ImportError: No module named 'xxx'
274+
275+
**Problem**: `ModuleNotFoundError` when importing an extension module.
276+
277+
**Reason**: The corresponding optional dependency is not installed.
278+
279+
**Solution**: Install the matching extension based on the missing module.
280+
281+
| Missing Module | Install Command |
282+
| ----------------------- | ------------------------------------------- |
283+
| `a2a_sdk` | `pip install "trpc-agent-py[a2a]"` |
284+
| `ag_ui_protocol` | `pip install "trpc-agent-py[ag-ui]"` |
285+
| `claude_agent_sdk` | `pip install "trpc-agent-py[agent-claude]"` |
286+
| `langchain_community` | `pip install "trpc-agent-py[knowledge]"` |
287+
| `mem0ai` | `pip install "trpc-agent-py[mem0]"` |
288+
| `langchain_tavily` | `pip install "trpc-agent-py[langchain_tool]"` |
289+
290+
---
291+
292+
### Pydantic version conflict
293+
294+
**Problem**:
295+
If your environment contains packages pinned to Pydantic v1, you may encounter errors such as:
296+
```text
297+
pydantic.errors.PydanticImportError: `BaseSettings` has been moved to the `pydantic-settings` package
298+
```
299+
Or other Pydantic v1/v2 compatibility errors.
300+
301+
**Solution**: This framework requires Pydantic v2 (>= 2.11.3).
302+
303+
```bash
304+
pip install --upgrade pydantic>=2.11.3
305+
```
306+
307+
If other packages depend on Pydantic v1, use an isolated virtual environment.
308+
309+
---
310+
311+
## Next Step
312+
313+
- **Quick Start**: Check out [examples/quickstart/](./examples/quickstart/) to run your first Agent quickly
314+
- **Full Documentation**: Visit the [docs/mkdocs/en/](./docs/mkdocs/en/)
315+
- **More Examples**: Browse the [examples/](./examples/) directory, covering multi-agent, tool calling, knowledge, memory, service deployment, etc.
316+
- **Contributing**: Read [CONTRIBUTING.md](./CONTRIBUTING.md)

0 commit comments

Comments
 (0)