From 4afb1020a7ff17e9383347ff4c9a35ebd13539e2 Mon Sep 17 00:00:00 2001 From: raychen <815315825@qq.com> Date: Fri, 7 Aug 2026 10:14:07 +0800 Subject: [PATCH] =?UTF-8?q?feature:=20=E4=BC=98=E5=8C=96=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E9=80=9F=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- INSTALL.md | 66 +++-- INSTALL.zh_CN.md | 64 +++-- README.md | 54 ++-- README.zh_CN.md | 66 ++++- build.sh | 266 +++++++++++++++++- build_mac.sh | 14 - build_mac_uv.sh | 40 --- clean.sh | 11 +- docs/mkdocs/en/a2a.md | 2 +- docs/mkdocs/en/agui.md | 2 +- docs/mkdocs/en/evaluation.md | 2 +- docs/mkdocs/en/graph.md | 2 +- docs/mkdocs/en/human_in_the_loop.md | 4 +- docs/mkdocs/en/skill.md | 2 +- docs/mkdocs/zh/a2a.md | 2 +- docs/mkdocs/zh/agui.md | 2 +- docs/mkdocs/zh/evaluation.md | 2 +- docs/mkdocs/zh/human_in_the_loop.md | 4 +- docs/mkdocs/zh/skill.md | 2 +- examples/a2a/README.md | 27 +- examples/a2a_with_cancel/README.md | 30 +- examples/agent_tools/README.md | 15 +- examples/agui/README.md | 15 +- examples/agui_with_cancel/README.md | 13 +- examples/claude_agent/README.md | 13 +- examples/claude_agent_with_cancel/README.md | 15 +- .../claude_agent_with_code_writer/README.md | 15 +- examples/claude_agent_with_skills/README.md | 15 +- .../README.md | 15 +- .../README.md | 15 +- examples/code_executors/README.md | 18 +- examples/dsl/classifier_mcp/README.md | 18 +- examples/dynamic_subagent/README.md | 30 +- examples/evaluation/callbacks/README.md | 2 +- .../evaluation/context_messages/README.md | 2 +- examples/evaluation/pass_at_k/README.md | 2 +- examples/evaluation/quickstart/README.md | 2 +- examples/evaluation/trace_mode/README.md | 2 +- examples/evaluation/webui/README.md | 2 +- examples/fastapi_server/README.md | 16 +- examples/file_tools/README.md | 15 +- examples/filter_with_agent/README.md | 15 +- examples/filter_with_model/README.md | 15 +- examples/filter_with_tool/README.md | 15 +- examples/function_tools/README.md | 15 +- examples/goal_tools/README.md | 31 +- examples/graph/README.md | 17 +- examples/graph_multi_turns/README.md | 15 +- examples/graph_with_interrupt/README.md | 15 +- .../README.md | 17 +- .../knowledge_with_documentloader/README.md | 23 +- .../knowledge_with_prompt_template/README.md | 26 +- examples/knowledge_with_rag_agent/README.md | 27 +- .../README.md | 29 +- examples/knowledge_with_vectorstore/README.md | 22 +- examples/langchain_tools/README.md | 16 +- examples/langgraph_agent/README.md | 15 +- examples/langgraph_agent_with_HITL/.env | 4 + .../README.md | 31 +- .../agent/__init__.py | 0 .../agent/agent.py | 0 .../agent/config.py | 0 .../agent/prompts.py | 0 .../agent/tools.py | 0 .../run_agent.py | 0 .../langgraph_agent_with_cancel/README.md | 15 +- .../.env | 4 - examples/litellm/README.md | 15 +- examples/llmagent/README.md | 15 +- .../llmagent_with_branch_filtering/README.md | 11 +- examples/llmagent_with_cancel/README.md | 15 +- examples/llmagent_with_custom_agent/README.md | 15 +- .../llmagent_with_custom_prompt/README.md | 15 +- .../llmagent_with_human_in_the_loop/README.md | 15 +- .../README.md | 15 +- .../llmagent_with_model_create_fn/README.md | 15 +- examples/llmagent_with_model_retry/README.md | 15 +- .../llmagent_with_parallal_tools/README.md | 15 +- examples/llmagent_with_prompt_cache/README.md | 15 +- examples/llmagent_with_schema/README.md | 15 +- .../README.md | 122 +++++--- .../README.md | 15 +- .../README.md | 15 +- examples/llmagent_with_thinking/README.md | 15 +- .../README.md | 15 +- examples/llmagent_with_tool_prompt/README.md | 15 +- examples/llmagent_with_user_history/README.md | 15 +- examples/mcp_tools/README.md | 15 +- examples/mem0_tools/README.md | 11 +- .../memory_service_with_in_memory/README.md | 15 +- examples/memory_service_with_mem0/README.md | 22 +- .../memory_service_with_mempalace/README.md | 25 +- examples/memory_service_with_redis/README.md | 29 +- examples/memory_service_with_sql/README.md | 16 +- examples/mempalace_mcp/README.md | 29 +- examples/mempalace_tools/README.md | 21 +- examples/multi_agent_chain/README.md | 15 +- examples/multi_agent_compose/README.md | 15 +- examples/multi_agent_cycle/README.md | 15 +- examples/multi_agent_parallel/README.md | 15 +- .../multi_agent_start_from_last/README.md | 15 +- examples/multi_agent_subagent/README.md | 15 +- examples/plan_mode/README.md | 28 +- .../plan_mode_with_goal_and_task/README.md | 27 +- examples/quickstart/README.md | 15 +- .../session_service_with_in_memory/README.md | 16 +- examples/session_service_with_redis/README.md | 25 +- examples/session_service_with_sql/README.md | 20 +- examples/session_state/README.md | 15 +- examples/session_summarizer/README.md | 15 +- examples/skills/README.md | 26 +- .../{.env.example => .env} | 0 examples/skills_code_review_agent/README.md | 22 +- examples/skills_hub/README.md | 28 +- examples/skills_with_container/README.md | 26 +- examples/skills_with_cube/README.md | 31 +- examples/skills_with_dynamic_tools/README.md | 26 +- examples/spawn_subagent/README.md | 27 +- examples/streaming_tools/README.md | 26 +- examples/task_tools/README.md | 15 +- examples/team/README.md | 26 +- examples/team_as_sub_agent/README.md | 2 +- examples/team_human_in_the_loop/README.md | 26 +- examples/team_member_agent_claude/README.md | 16 +- .../team_member_agent_langgraph/README.md | 26 +- examples/team_member_agent_team/README.md | 24 +- examples/team_member_message_filter/README.md | 26 +- examples/team_parallel_execution/README.md | 27 +- examples/team_with_cancel/README.md | 26 +- examples/team_with_skill/README.md | 27 +- examples/todo_tool/README.md | 15 +- .../README.md | 15 +- examples/tools/README.md | 16 +- examples/toolsets/README.md | 25 +- examples/transfer_agent/README.md | 15 +- examples/webfetch_tool/README.md | 15 +- examples/websearch_tool/README.md | 15 +- pipeline_test/_install_deps.sh | 83 ++++++ pipeline_test/run_agent_examples.sh | 42 ++- pipeline_test/run_all_examples.sh | 64 +++++ pipeline_test/run_ecosystem_examples.sh | 42 ++- pipeline_test/run_evaluation_examples.sh | 41 ++- pipeline_test/run_other_examples.sh | 31 +- pyproject.toml | 44 +-- .../test_optional_graph_dependencies.py | 42 +++ trpc_agent_sdk/agents/__init__.py | 44 ++- trpc_agent_sdk/agents/utils/__init__.py | 43 ++- .../agents/utils/_langgraph_event_writer.py | 4 +- .../dsl/graph/_node_action/_knowledge.py | 6 +- trpc_agent_sdk/dsl/graph/_state_graph.py | 6 +- trpc_agent_sdk/knowledge/_knowledge.py | 9 +- .../server/knowledge/langchain_knowledge.py | 9 +- 152 files changed, 2159 insertions(+), 1028 deletions(-) delete mode 100644 build_mac.sh delete mode 100755 build_mac_uv.sh create mode 100644 examples/langgraph_agent_with_HITL/.env rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/README.md (86%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/agent/__init__.py (100%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/agent/agent.py (100%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/agent/config.py (100%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/agent/prompts.py (100%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/agent/tools.py (100%) rename examples/{langgraphagent_with_human_in_the_loop => langgraph_agent_with_HITL}/run_agent.py (100%) delete mode 100644 examples/langgraphagent_with_human_in_the_loop/.env rename examples/skills_code_review_agent/{.env.example => .env} (100%) create mode 100644 pipeline_test/_install_deps.sh create mode 100644 tests/agents/test_optional_graph_dependencies.py diff --git a/INSTALL.md b/INSTALL.md index 49665def8..a604a066c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -65,7 +65,7 @@ Install optional extensions: ```bash # Choose as needed, multiple extensions can be combined with commas -pip install "trpc-agent-py[a2a,knowledge,agent-claude]" +pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" ``` --- @@ -77,29 +77,53 @@ pip install "trpc-agent-py[a2a,knowledge,agent-claude]" git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python # Create and activate a virtual environment -python3 -m venv .venv +./build.sh source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows -# Install -pip install -e . ``` ### uv Installation -[uv](https://docs.astral.sh/uv/) manages the Python toolchain, virtual environment and dependencies based on the repository's `pyproject.toml` for fast, reproducible installs. This project provides a script for one-shot setup on macOS: +[uv](https://docs.astral.sh/uv/) provides fast dependency installation. + +#### Install in a user project (recommended) + +```bash +# Install uv if it is not already available +python -m pip install uv + +# Install the published package in a virtual environment +uv venv --python 3.12 +source .venv/bin/activate +uv pip install trpc-agent-py + +# Install optional capabilities as needed +# uv pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" +``` + +For a project managed by uv: + +```bash +# Core package only +uv add trpc-agent-py +# Or: core + optional extras (one command is enough) +# uv add "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" +``` + +#### Develop this repository from source + +After cloning the repository, use the same cross-platform build script: ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -# Install uv on macOS (see https://docs.astral.sh/uv/getting-started/installation/) -curl -LsSf https://astral.sh/uv/install.sh | sh - -# One-shot setup -bash build_mac_uv.sh +./build.sh uv -# add optional extras -EXTRAS="a2a knowledge" bash build_mac_uv.sh +# Or: core + optional extras (one command is enough; installer defaults to uv) +# ./build.sh "[dev,graph,a2a,knowledge,knowledge-hf]" +# ./build.sh uv "[dev,graph,a2a,knowledge,knowledge-hf]" +source .venv/bin/activate ``` Or run the steps manually: @@ -107,10 +131,10 @@ Or run the steps manually: ```bash uv venv --python-preference only-system # use the local Python uv sync --extra dev # core + dev tooling -uv sync --extra a2a --extra knowledge # add optional extras +uv sync --extra graph --extra a2a --extra knowledge --extra knowledge-hf uv sync # production install (core only) -# Run commands inside the environment without activating it for evaluation +# Run commands inside the environment without activating it uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)" ``` @@ -118,6 +142,8 @@ To speed up downloads via a mirror, pass `--default-index`, e.g.: ```bash uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple +# Or in a user project: +# uv pip install trpc-agent-py --index-url https://mirrors.cloud.tencent.com/pypi/simple ``` ### Optional Dependencies Reference @@ -127,7 +153,9 @@ uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple | `a2a` | Google A2A protocol | `pip install "trpc-agent-py[a2a]"` | | `ag-ui` | AG-UI protocol | `pip install "trpc-agent-py[ag-ui]"` | | `agent-claude` | Claude Agent | `pip install "trpc-agent-py[agent-claude]"` | +| `graph` | LangGraphAgent and graph DSL (includes langchain) | `pip install "trpc-agent-py[graph]"` | | `knowledge` | Knowledge base / RAG | `pip install "trpc-agent-py[knowledge]"` | +| `knowledge-hf` | Hugging Face embeddings | `pip install "trpc-agent-py[knowledge-hf]"` | | `mem0` | Long-term memory (Mem0) | `pip install "trpc-agent-py[mem0]"` | | `langchain_tool` | LangChain Tool integration | `pip install "trpc-agent-py[langchain_tool]"` | | `langfuse` | Langfuse observability | `pip install "trpc-agent-py[langfuse]"` | @@ -163,6 +191,7 @@ TRPC_AGENT_MODEL_NAME="your-model-name" **Option 2**: Export directly to the shell environment ```bash +# Export environment variables export TRPC_AGENT_API_KEY="your-api-key" export TRPC_AGENT_BASE_URL="your-base-url" export TRPC_AGENT_MODEL_NAME="your-model-name" @@ -202,6 +231,7 @@ Expected output: ``` All core modules imported successfully. ``` + ### Run Unit Tests ```bash @@ -220,10 +250,10 @@ pytest tests/ -v **Solution**: Use a mirror to speed up downloads. ```bash -# Temporary usage Tencent Cloud mirror +# Temporary usage pip install trpc-agent-py -i https://mirrors.cloud.tencent.com/pypi/simple -# Set global Tencent Cloud mirror +# Set global mirror pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple ``` @@ -243,10 +273,10 @@ Other available mirrors: ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10' ``` -**Solution**: Upgrade to Python 3.12. +**Solution**: Upgrade to Python3.12. ```bash -# Solution 1: Using pyenv to install Python 3.12 +# Solution 1: Using pyenv to install Python3.12 pyenv install 3.12 pyenv local 3.12 diff --git a/INSTALL.zh_CN.md b/INSTALL.zh_CN.md index b1ff2f36e..3f9d6f8cd 100644 --- a/INSTALL.zh_CN.md +++ b/INSTALL.zh_CN.md @@ -50,6 +50,8 @@ ### Pip 安装 +#### 在用户项目中安装（推荐） + ```bash # 创建虚拟环境 python3 -m venv .venv @@ -65,41 +67,65 @@ pip install trpc-agent-py ```bash # 按需选择，多个扩展可用逗号组合 -pip install "trpc-agent-py[a2a,knowledge,agent-claude]" +pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" ``` ---- - -### 源码安装 +#### 从源码开发本仓库 ```bash # 克隆仓库 git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python # 创建并激活虚拟环境 -python3 -m venv .venv +./build.sh pip source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows -# 安装 -pip install -e . ``` +--- + ### uv 安装 -[uv](https://docs.astral.sh/uv/) 会基于仓库中 `pyproject.toml` 管理 Python 工具链、虚拟环境与依赖，实现快速、可复现的安装，本项目提供脚本在 macOS 上一键安装运行： +[uv](https://docs.astral.sh/uv/) 可以快速安装依赖。 + +#### 在用户项目中安装（推荐） + +```bash +# 如果尚未安装 uv，先安装 +python -m pip install uv + +# 在虚拟环境中安装已发布的包 +uv venv --python 3.12 +source .venv/bin/activate +uv pip install trpc-agent-py + +# 按需安装扩展能力 +# uv pip install "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" +``` + +对于由 uv 管理的项目： + +```bash +# 只要核心能力 +uv add trpc-agent-py +# 需要扩展能力（一条就够） +# uv add "trpc-agent-py[graph,a2a,knowledge,knowledge-hf,agent-claude]" +``` + +#### 从源码开发本仓库 + +克隆仓库后，可使用与其他平台相同的构建脚本： ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -# 在 macOS 上安装 uv（参考 https://docs.astral.sh/uv/getting-started/installation/） -curl -LsSf https://astral.sh/uv/install.sh | sh +./build.sh uv -# 一键初始化核心依赖 -bash build_mac_uv.sh - -# 按需追加可选扩展 -EXTRAS="a2a knowledge" bash build_mac_uv.sh +# 需要扩展能力（一条就够；省略 uv 时默认仍用 uv） +# ./build.sh "[dev,graph,a2a,knowledge,knowledge-hf]" +# ./build.sh uv "[dev,graph,a2a,knowledge,knowledge-hf]" +source .venv/bin/activate ``` 或者使用手动执行的方式： @@ -107,7 +133,7 @@ EXTRAS="a2a knowledge" bash build_mac_uv.sh ```bash uv venv --python-preference only-system # 使用本地已安装的 Python uv sync --extra dev # 核心依赖 + 开发工具 -uv sync --extra a2a --extra knowledge # 按需追加可选扩展 +uv sync --extra graph --extra a2a --extra knowledge --extra knowledge-hf uv sync # 生产安装（仅核心依赖） # 无需激活环境即可运行命令验证 @@ -118,6 +144,8 @@ uv run python -c "from trpc_agent_sdk.version import __version__; print(__versio ```bash uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple +# 或在用户项目中： +# uv pip install trpc-agent-py --index-url https://mirrors.cloud.tencent.com/pypi/simple ``` ### 可选依赖对照表 @@ -127,7 +155,9 @@ uv sync --default-index https://mirrors.cloud.tencent.com/pypi/simple | `a2a` | Google A2A 协议 | `pip install "trpc-agent-py[a2a]"` | | `ag-ui` | AG-UI 协议 | `pip install "trpc-agent-py[ag-ui]"` | | `agent-claude` | Claude Agent | `pip install "trpc-agent-py[agent-claude]"` | +| `graph` | LangGraphAgent 与图 DSL（含 langchain） | `pip install "trpc-agent-py[graph]"` | | `knowledge` | 知识库 / RAG | `pip install "trpc-agent-py[knowledge]"` | +| `knowledge-hf` | Hugging Face 嵌入模型 | `pip install "trpc-agent-py[knowledge-hf]"` | | `mem0` | 长期记忆（Mem0） | `pip install "trpc-agent-py[mem0]"` | | `langchain_tool` | LangChain Tool 集成 | `pip install "trpc-agent-py[langchain_tool]"` | | `langfuse` | Langfuse 可观测性 | `pip install "trpc-agent-py[langfuse]"` | @@ -245,7 +275,7 @@ pip config set global.index-url https://mirrors.cloud.tencent.com/pypi/simple ERROR: Package 'trpc-agent-py' requires a different Python: 3.9.x not in '>=3.10' ``` -**解决方案**：升级到 Python 3.12。 +**解决方案**：升级到 Python3.12。 ```bash # 解决方案 1: 使用 pyenv 安装 diff --git a/README.md b/README.md index b2c91e7d3..3329de390 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ tRPC-Agent-Python provides an end-to-end foundation for agent building, orchestr ### Prerequisites -- Python 3.10+ (Python 3.12 recommended) +- Python3.10+ (Python3.12 recommended) - Available model API key (OpenAI-like / Anthropic, or route via LiteLLM) ### Installation @@ -86,7 +86,7 @@ pip install trpc-agent-py Install optional capabilities as needed: ```bash -pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]" +pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf,agent-claude,mem0,mempalace,langfuse]" ``` #### Install with uv @@ -94,26 +94,48 @@ pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langf [uv](https://docs.astral.sh/uv/) provides fast, reproducible installs: ```bash -uv venv --python-preference only-system # use the local Python -uv sync # production install (core only) -uv sync --extra dev # core + dev tooling -uv sync --extra a2a --extra knowledge # add optional extras +# Install uv if it is not already available +python -m pip install uv +# Install the published package in a virtual environment +uv venv --python 3.12 +source .venv/bin/activate +uv pip install trpc-agent-py -# Run commands inside the environment without activating it for evaluation -uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)" +# Install optional capabilities as needed +# uv pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]" ``` -This project also provides a script for one-shot setup on macOS： +For a project managed by uv: + ```bash -# One-shot setup -bash build_mac_uv.sh +# Core package only +uv add trpc-agent-py +# Or: core + optional extras (one command is enough) +# uv add "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]" ``` -Install optional capabilities as needed: +When developing this repository: + +```bash +uv sync --extra dev +./build.sh # uv (default; installed automatically if missing) +# ./build.sh "[graph]" # uv by default, extras only +# ./build.sh pip # use pip instead +# ./build.sh uv "[dev,graph]" # explicit uv with selected extras + +# Install dependencies required by feature-specific test suites +./build.sh uv "[dev,graph,ag-ui,agent-claude,a2a]" +uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)" +``` +On macOS, use the same cross-platform build script inside a virtual environment: ```bash -EXTRAS="a2a knowledge" bash build_mac_uv.sh +./build.sh # creates .venv automatically; default uv +#./build.sh "[dev,graph,knowledge]" # uv by default with selected extras +#./build.sh pip "[dev]" # use pip +#./build.sh uv "[dev,graph,knowledge]" # explicit uv +source .venv/bin/activate # activate it in the current shell ``` ### Develop Weather Agent @@ -371,7 +393,7 @@ Recommended first: - [examples/langgraph_agent](./examples/langgraph_agent/README.md) - Integrate pre-built and compiled LangGraph workflows - [examples/langgraph_agent_with_cancel](./examples/langgraph_agent_with_cancel/README.md) - `LangGraphAgent` cancellation -- [examples/langgraphagent_with_human_in_the_loop](./examples/langgraphagent_with_human_in_the_loop/README.md) - `LangGraphAgent` human-in-the-loop +- [examples/langgraph_agent_with_HITL](./examples/langgraph_agent_with_HITL/README.md) - `LangGraphAgent` human-in-the-loop - [examples/claude_agent](./examples/claude_agent/README.md) - `ClaudeAgent` basics - [examples/claude_agent_with_streaming_tool](./examples/claude_agent_with_streaming_tool/README.md) - `ClaudeAgent` streaming tools - [examples/claude_agent_with_skills](./examples/claude_agent_with_skills/README.md) - `ClaudeAgent` + Skills @@ -615,8 +637,8 @@ We love contributions! Join our growing developer community and help build the f git clone https://github.com/YOUR_USERNAME/trpc-agent-python.git cd trpc-agent-python -# Install development dependencies and run tests -pip install -e ".[dev]" +# Install development and feature-test dependencies, then run tests +pip install -e ".[dev,graph,ag-ui,agent-claude,a2a]" pytest # Make your changes and open a PR! diff --git a/README.zh_CN.md b/README.zh_CN.md index ca4c5f3be..e7acf592d 100644 --- a/README.zh_CN.md +++ b/README.zh_CN.md @@ -1,4 +1,4 @@ -[English](README.md) | 中文 +[English](README.md) | [中文](README.zh_CN.md) # tRPC-Agent-Python @@ -72,11 +72,13 @@ tRPC-Agent-Python 提供从 Agent 构建、编排、工具接入、会话记忆 ### 前置条件 -- Python 3.10+（推荐 Python 3.12） +- Python3.10+（推荐 Python3.12） - 可用的模型服务 API Key（OpenAI-like / Anthropic，或通过 LiteLLM 路由） ### 安装 +#### 使用 pip 安装 + ```bash pip install trpc-agent-py ``` @@ -84,10 +86,60 @@ pip install trpc-agent-py 按需安装扩展能力： ```bash -pip install "trpc-agent-py[a2a,ag-ui,knowledge,agent-claude,mem0,mempalace,langfuse]" +pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf,agent-claude,mem0,mempalace,langfuse]" +``` + +#### 使用 uv 安装 + +[uv](https://docs.astral.sh/uv/) 可提供更快、可复现的安装体验： + +```bash +# 如果尚未安装 uv，先安装 +python -m pip install uv + +# 在虚拟环境中安装已发布的包 +uv venv --python 3.12 +source .venv/bin/activate +uv pip install trpc-agent-py + +# 按需安装扩展能力 +uv pip install "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]" +``` + +对于由 uv 管理的项目： + +```bash +# 只要核心能力 +uv add trpc-agent-py +# 需要扩展能力（一条就够） +#uv add "trpc-agent-py[graph,a2a,ag-ui,knowledge,knowledge-hf]" +``` + +开发本仓库时： + +```bash +uv sync --extra dev +./build.sh # 默认使用 uv（缺失时会自动安装） +# ./build.sh "[graph]" # 默认 uv，仅指定 extras +# ./build.sh pip # 改用 pip +# ./build.sh uv "[dev,graph]" # 显式 uv，并选择 extras + +# 安装功能相关测试所需依赖 +./build.sh uv "[dev,graph,ag-ui,agent-claude,a2a]" +uv run python -c "from trpc_agent_sdk.version import __version__; print(__version__)" +``` + +在 macOS 上，同样使用跨平台的构建脚本，并在虚拟环境中运行： + +```bash +./build.sh # 自动创建 .venv，默认 uv +# ./build.sh "[dev,graph,knowledge]" # 默认 uv，选择 extras +# ./build.sh pip "[dev]" # 使用 pip +# ./build.sh uv "[dev,graph,knowledge]" # 显式 uv +source .venv/bin/activate # 在当前 shell 中激活环境 ``` -### 开发天气查询Agent +### 开发天气查询 Agent ```python import asyncio @@ -342,7 +394,7 @@ graph.add_conditional_edges( - [examples/langgraph_agent](./examples/langgraph_agent/README.md) - 对接用户使用 LangGraph 开发并 compile 的 Agent 工作流 - [examples/langgraph_agent_with_cancel](./examples/langgraph_agent_with_cancel/README.md) - LangGraphAgent 任务取消 -- [examples/langgraphagent_with_human_in_the_loop](./examples/langgraphagent_with_human_in_the_loop/README.md) - LangGraphAgent 人机协同 +- [examples/langgraph_agent_with_HITL](./examples/langgraph_agent_with_HITL/README.md) - LangGraphAgent 人机协同 - [examples/claude_agent](./examples/claude_agent/README.md) - ClaudeAgent 基础用法 - [examples/claude_agent_with_streaming_tool](./examples/claude_agent_with_streaming_tool/README.md) - ClaudeAgent 流式工具调用 - [examples/claude_agent_with_skills](./examples/claude_agent_with_skills/README.md) - ClaudeAgent + Skills @@ -586,8 +638,8 @@ skill_tool_set = SkillToolSet(repository=repository, run_tool_kwargs=tool_kwargs git clone https://github.com/YOUR_USERNAME/trpc-agent-python.git cd trpc-agent-python -# 安装开发依赖并运行测试 -pip install -e ".[dev]" +# 安装开发与功能测试依赖，然后运行测试 +pip install -e ".[dev,graph,ag-ui,agent-claude,a2a]" pytest # 进行您的更改并提交 PR！ diff --git a/build.sh b/build.sh index f7dba5ffa..ddf78cf0b 100755 --- a/build.sh +++ b/build.sh @@ -1,14 +1,264 @@ -#!/bin/bash +#!/usr/bin/env bash -pip install --upgrade pip +set -e +show_help() { + cat <<'EOF' +Usage: + ./build.sh + ./build.sh "[extras]" + ./build.sh uv|pip "[extras]" + ./build.sh help -sh clean.sh +Arguments: + uv|pip Dependency installer. Defaults to uv when omitted. + extras Optional dependency groups from pyproject.toml, written like + pip extras: "[graph]" or "[dev,graph,a2a]". + Defaults to "[dev]" when omitted. -pip3 install -r requirements.txt -pip3 install -r requirements-test.txt +Environment behavior: + - Reuses a healthy project virtual environment first (.venv, then venv) and runs clean.sh against it. + - Without a project venv, reuses an active environment or creates .venv. + - clean.sh is skipped for active external or newly created environments. + - Installs uv automatically when uv is selected but unavailable. + - Disables pip/uv caches by default to better match cold user installs. + - After a pip install, activate a newly created environment with: + source .venv/bin/activate + For example: + source .venv/bin/activate + python3 + - After a uv install, run commands without activation with: + uv run --no-sync -pip install -e .[dev] +Examples: + ./build.sh + Install the [dev] extra with uv (default). -# 检查依赖解析 -pip install --dry-run . + ./build.sh "[graph]" + Install the [graph] extra with uv (default installer). + + ./build.sh uv "[dev,graph]" + Install development and LangGraph/DSL dependencies with uv. + + ./build.sh pip + Install with pip ([dev] extra). + + ./build.sh pip "[dev,knowledge,knowledge-hf]" + Install development and Knowledge/Hugging Face dependencies with pip. + + ./build.sh uv "[dev,graph,ag-ui,agent-claude,a2a]" + Install dependencies needed by feature-specific test suites. + +Optional environment variables: + PYTHON_BIN Python used to create or select the environment (default: python3). + SKIP_CLEAN Set to 1 to skip cleaning an existing project .venv. + USE_CACHE Set to 1 to allow pip/uv caches (default: disabled). + PIP_INDEX_URL / UV_DEFAULT_INDEX + Custom package indexes used by pip and uv. + +Environment variable examples: + PYTHON_BIN=python3.12 ./build.sh uv "[dev,graph]" + Create/select the environment with Python 3.12. + + SKIP_CLEAN=1 ./build.sh uv "[dev]" + Keep packages already installed in the existing project .venv. + + USE_CACHE=1 ./build.sh uv "[dev]" + Reuse local pip/uv caches for faster repeated installs. + + PIP_INDEX_URL=https://mirror.example/simple ./build.sh pip + Install through a custom pip package index. + + PIP_INDEX_URL=https://mirror.example/simple \ + UV_DEFAULT_INDEX=https://mirror.example/simple \ + ./build.sh uv "[dev,graph]" + Install uv itself and project dependencies through a custom index. +EOF +} + +normalize_extras() { + local raw="${1:?extras required}" + raw="${raw//[[:space:]]/}" + if [[ "${raw}" == \[*\] ]]; then + raw="${raw:1:${#raw}-2}" + fi + if [[ -z "${raw}" ]]; then + echo "Extras list cannot be empty. Use e.g. \"[graph]\" or \"[dev,graph]\"." >&2 + exit 2 + fi + printf '%s\n' "${raw}" +} + +case "${1:-}" in + help|-h|--help) + show_help + exit 0 + ;; +esac + +PYTHON_BIN="${PYTHON_BIN:-python3}" +CREATED_VENV=0 +RUN_CLEAN=0 +USE_CACHE="${USE_CACHE:-0}" +PIP_CACHE_ARGS=() +UV_CACHE_ARGS=() + +# Parse: ./build.sh +# ./build.sh "[extras]" +# ./build.sh uv|pip +# ./build.sh uv|pip "[extras]" +INSTALLER="uv" +EXTRAS="dev" + +if (( $# > 2 )); then + show_help >&2 + exit 2 +elif (( $# == 0 )); then + : +elif [[ "$1" == "pip" || "$1" == "uv" ]]; then + INSTALLER="$1" + if (( $# == 2 )); then + EXTRAS="$(normalize_extras "$2")" + fi +else + # First argument is extras like "[graph]"; installer stays uv. + EXTRAS="$(normalize_extras "$1")" + if (( $# == 2 )); then + echo "Unexpected second argument '$2' after extras '$1'." >&2 + echo "Use: ./build.sh \"[extras]\" or ./build.sh uv|pip \"[extras]\"" >&2 + echo "Run './build.sh help' for usage." >&2 + exit 2 + fi +fi + +INSTALL_SPEC=".[${EXTRAS}]" + +case "${INSTALLER}" in + pip|uv) ;; + *) + echo "Unsupported INSTALLER=${INSTALLER}; use pip or uv." >&2 + echo "Run './build.sh help' for usage." >&2 + exit 2 + ;; +esac + +echo "Installer: ${INSTALLER}; extras: [${EXTRAS}]" + +if [[ "${USE_CACHE}" != "1" ]]; then + export PIP_NO_CACHE_DIR=1 + export UV_NO_CACHE=1 + PIP_CACHE_ARGS=(--no-cache-dir) + UV_CACHE_ARGS=(--no-cache) + echo "Package caches disabled (cold-install mode)." +else + echo "Package caches enabled." +fi + +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if [[ "${SKIP_CLEAN:-0}" == "1" ]] && is_virtualenv_python "${PYTHON_BIN}"; then + echo "Using the explicitly selected virtual environment; clean.sh will be skipped." +elif PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Reusing existing project virtual environment: ${PROJECT_VENV_DIR}" + PYTHON_BIN="$(pwd)/${PROJECT_VENV_DIR}/bin/python" + RUN_CLEAN=1 +elif is_virtualenv_python "${PYTHON_BIN}"; then + echo "Using the active virtual environment; clean.sh will be skipped." +else + if [[ -e .venv || -L .venv ]]; then + echo "Existing .venv is invalid; removing it before recreation..." + rm -rf .venv + fi + echo "No project virtual environment detected; creating .venv..." + if ! "${PYTHON_BIN}" -m venv .venv; then + rm -rf .venv + echo "Failed to create .venv with ${PYTHON_BIN}." >&2 + echo "Ensure the Python venv/ensurepip component is installed, then retry." >&2 + exit 1 + fi + PROJECT_VENV_DIR=".venv" + PYTHON_BIN="$(pwd)/.venv/bin/python" + CREATED_VENV=1 +fi + +# Activate the selected environment inside this script so helper scripts that +# call pip/pip3 also operate on the same environment. +VENV_DIR="$("${PYTHON_BIN}" -c 'import sys; print(sys.prefix)')" +if [[ -f "${VENV_DIR}/bin/activate" ]]; then + source "${VENV_DIR}/bin/activate" +else + export PATH="${VENV_DIR}/bin:${PATH}" +fi +PYTHON_BIN="${VENV_DIR}/bin/python" +echo "Using virtual environment: ${VENV_DIR}" + +if [[ "${RUN_CLEAN}" == "1" && "${SKIP_CLEAN:-0}" != "1" ]]; then + echo "Cleaning the existing project virtual environment..." + sh clean.sh +fi + +case "${INSTALLER}" in + pip) + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" --upgrade pip + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" -r requirements.txt + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" -r requirements-test.txt + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" --editable "${INSTALL_SPEC}" + # 检查依赖解析 + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" --dry-run . + ;; + uv) + # uv 只是开发安装工具，不需要加入项目运行时依赖。 + if ! "${PYTHON_BIN}" -m uv --version >/dev/null 2>&1; then + "${PYTHON_BIN}" -m pip install "${PIP_CACHE_ARGS[@]}" --upgrade uv + fi + "${PYTHON_BIN}" -m uv pip install \ + "${UV_CACHE_ARGS[@]}" \ + --python "${PYTHON_BIN}" \ + --editable "${INSTALL_SPEC}" + "${PYTHON_BIN}" -m uv pip check --python "${PYTHON_BIN}" + # 检查依赖解析 + "${PYTHON_BIN}" -m uv pip install \ + "${UV_CACHE_ARGS[@]}" \ + --python "${PYTHON_BIN}" \ + --dry-run . + ;; +esac + +case "${INSTALLER}" in + pip) + if [[ "${CREATED_VENV}" == "1" ]]; then + echo "Virtual environment created at ${PROJECT_VENV_DIR:-.venv}" + echo "Activate it in your shell with: source ${PROJECT_VENV_DIR:-.venv}/bin/activate" + echo "For example:" + echo "source ${PROJECT_VENV_DIR:-.venv}/bin/activate" + echo " python3 " + else + echo "Installation completed in the active virtual environment: ${VENV_DIR}" + echo "For example:" + echo "python3 -m venv .venv && source .venv/bin/activate" + echo " python3 " + fi + ;; + uv) + echo "Run project commands without activating the environment:" + echo " uv run --no-sync " + echo "For example:" + echo " uv run --no-sync pytest" + ;; +esac diff --git a/build_mac.sh b/build_mac.sh deleted file mode 100644 index 723f2e011..000000000 --- a/build_mac.sh +++ /dev/null @@ -1,14 +0,0 @@ -# 先注释 -set -e - -pip install --upgrade pip - -sh clean.sh - -pip install -r requirements.txt -pip install -r requirements-test.txt - -pip install -e '.[dev]' - -# 检查依赖解析 -pip install --dry-run . diff --git a/build_mac_uv.sh b/build_mac_uv.sh deleted file mode 100755 index 030550942..000000000 --- a/build_mac_uv.sh +++ /dev/null @@ -1,40 +0,0 @@ -#!/usr/bin/env bash -# -# uv-based development setup for trpc-agent-python (macOS). -# -# This is a standalone alternative to build_mac.sh (which uses pip). -# It uses uv to manage the Python toolchain, virtualenv and dependencies. -# -# Usage: -# bash build_mac_uv.sh # core + dev extra -# EXTRAS="a2a knowledge" bash build_mac_uv.sh # also install extras -# -set -euo pipefail - -# Make sure uv's default install location is on PATH before probing for uv, -# so a previously installed uv is reused instead of reinstalled every run. -export PATH="$HOME/.local/bin:$PATH" - -# 1. Ensure uv is available. -if ! command -v uv >/dev/null 2>&1; then - echo "[build_mac_uv] uv not found, installing..." - curl -LsSf https://astral.sh/uv/install.sh | sh - export PATH="$HOME/.local/bin:$PATH" -fi - -echo "[build_mac_uv] uv version: $(uv --version)" - -# 2. Create the virtual environment using the user's local Python. -uv venv --python-preference only-system - -# 3. Sync dependencies: core + the `dev` extra, plus any requested extras. -EXTRA_ARGS=() -for e in ${EXTRAS:-}; do - EXTRA_ARGS+=("--extra" "$e") -done -uv sync --extra dev ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"} - -# 4. Smoke test the installation. -uv run python -c "import trpc_agent_sdk; from trpc_agent_sdk.version import __version__; print(f'trpc-agent-py {__version__} installed via uv')" - -echo "[build_mac_uv] Done. Activate the env with: source .venv/bin/activate" diff --git a/clean.sh b/clean.sh index 551a56ae1..937f91157 100755 --- a/clean.sh +++ b/clean.sh @@ -20,12 +20,13 @@ sudo rm -rf examples/.__py_trpc_frame.lock sudo rm -rf examples/.__trpc.lock -find -type d | grep __pycache__ | xargs sudo rm -r +find . -type d -name __pycache__ -prune -exec sudo rm -rf {} + find ./ -type f -name "*.log" -exec sudo rm {} \; -pip3 freeze > tmp_requirements.txt -pip3 uninstall -r tmp_requirements.txt -y - -sudo rm tmp_requirements.txt +python -m pip freeze > tmp_requirements.txt +if [ -s tmp_requirements.txt ]; then + python -m pip uninstall -r tmp_requirements.txt -y +fi +sudo rm -f tmp_requirements.txt diff --git a/docs/mkdocs/en/a2a.md b/docs/mkdocs/en/a2a.md index 5bea91de9..ff68bd4f4 100644 --- a/docs/mkdocs/en/a2a.md +++ b/docs/mkdocs/en/a2a.md @@ -17,7 +17,7 @@ The trpc-agent-python SDK includes built-in Agent-to-Agent (A2A) protocol suppor pip install -e ".[a2a]" ``` -Python 3.12 is required. +Python3.12 is required. --- diff --git a/docs/mkdocs/en/agui.md b/docs/mkdocs/en/agui.md index d04d35f4e..bfc2e53e9 100644 --- a/docs/mkdocs/en/agui.md +++ b/docs/mkdocs/en/agui.md @@ -18,7 +18,7 @@ From the repository root after cloning (enable the `ag-ui` optional extra): pip install -e ".[ag-ui]" ``` -Python 3.12 is required. Core dependencies include `ag-ui-protocol` and `FastAPI/Uvicorn`. +Python3.12 is required. Core dependencies include `ag-ui-protocol` and `FastAPI/Uvicorn`. ## Quick Start diff --git a/docs/mkdocs/en/evaluation.md b/docs/mkdocs/en/evaluation.md index 9028b06d7..40578be0a 100644 --- a/docs/mkdocs/en/evaluation.md +++ b/docs/mkdocs/en/evaluation.md @@ -104,7 +104,7 @@ This section provides a minimal runnable example to help you complete your first #### Step 1: Environment Setup -**System Requirements**: Python 3.12 is required; you also need an accessible LLM model service. +**System Requirements**: Python3.12 is required; you also need an accessible LLM model service. **Install Dependencies** (includes pytest, pytest-asyncio, rouge-score, etc.): diff --git a/docs/mkdocs/en/graph.md b/docs/mkdocs/en/graph.md index 5726be593..bd30d925b 100644 --- a/docs/mkdocs/en/graph.md +++ b/docs/mkdocs/en/graph.md @@ -15,7 +15,7 @@ As shown below, users build graphs through the Graph API provided by the framewo It is recommended to configure your environment with the following constraints: - **Custom nodes must be defined using `async def` to prevent issues caused by mixing synchronous and asynchronous code (e.g., blocking the EventLoop)** -- **Python 3.12**: *This constraint is imposed by the graph execution engine LangGraph. The Graph engine wrapper requires nodes to stream various information during execution, a capability Python supports on 3.11 and above.* +- **Python3.12**: *This constraint is imposed by the graph execution engine LangGraph. The Graph engine wrapper requires nodes to stream various information during execution, a capability Python supports on 3.11 and above.* - **LangGraph version 1.0.x stable release is recommended** diff --git a/docs/mkdocs/en/human_in_the_loop.md b/docs/mkdocs/en/human_in_the_loop.md index 7d11cb53c..9ff670738 100644 --- a/docs/mkdocs/en/human_in_the_loop.md +++ b/docs/mkdocs/en/human_in_the_loop.md @@ -1,4 +1,4 @@ -# Human-In-The-Loop +# Human-In-The-Loop(HITL) During Agent processing, some scenarios require human involvement for judgment or adjustment to improve task completion accuracy. Examples include: - Risky operation approval: Commonly used when an Agent generates SQL or Shell scripts, whether to execute them often requires human approval. Taking Agent-generated command lines as an example, if approved, the terminal is launched to execute the command and the execution result is passed back to the Agent; if rejected, it may indicate the generated command is problematic and the Agent needs to regenerate an alternative command. @@ -432,4 +432,4 @@ async def run_human_in_loop_agent(): For complete example code, please refer to: - LlmAgent: [examples/llmagent_with_human_in_the_loop/README.md](../../../examples/llmagent_with_human_in_the_loop/README.md) -- LangGraphAgent: [examples/langgraphagent_with_human_in_the_loop/README.md](../../../examples/langgraphagent_with_human_in_the_loop/README.md) +- LangGraphAgent: [examples/langgraph_agent_with_HITL/README.md](../../../examples/langgraph_agent_with_HITL/README.md) diff --git a/docs/mkdocs/en/skill.md b/docs/mkdocs/en/skill.md index 60a9120e1..9d09c8d54 100644 --- a/docs/mkdocs/en/skill.md +++ b/docs/mkdocs/en/skill.md @@ -61,7 +61,7 @@ Repository and parsing: [trpc_agent_sdk/skills/_repository.py](../../../trpc_age ### 1) Requirements -- Python 3.12 +- Python3.12 - Model provider API key (OpenAI-compatible) - Optional Docker (for container executor) diff --git a/docs/mkdocs/zh/a2a.md b/docs/mkdocs/zh/a2a.md index 18e1286dd..b1ca062bd 100644 --- a/docs/mkdocs/zh/a2a.md +++ b/docs/mkdocs/zh/a2a.md @@ -17,7 +17,7 @@ trpc-agent SDK 内置了 Agent-to-Agent (A2A) 协议支持，让你可以将本 pip install -e ".[a2a]" ``` -需要使用 Python 3.12。 +需要使用 Python3.12。 --- diff --git a/docs/mkdocs/zh/agui.md b/docs/mkdocs/zh/agui.md index 6b1030811..a9fe8b6f4 100644 --- a/docs/mkdocs/zh/agui.md +++ b/docs/mkdocs/zh/agui.md @@ -18,7 +18,7 @@ pip install -e ".[ag-ui]" ``` -要求使用 Python 3.12。核心依赖包含 `ag-ui-protocol` 与 `FastAPI/Uvicorn`。 +要求使用 Python3.12。核心依赖包含 `ag-ui-protocol` 与 `FastAPI/Uvicorn`。 ## 快速上手 diff --git a/docs/mkdocs/zh/evaluation.md b/docs/mkdocs/zh/evaluation.md index 68a9eed8b..e4698740d 100644 --- a/docs/mkdocs/zh/evaluation.md +++ b/docs/mkdocs/zh/evaluation.md @@ -101,7 +101,7 @@ tRPC-Agent 评测模块是一套**自动化 Agent 质量检验工具**。它让 #### 第一步：环境准备 -**系统要求**：Python 3.12，可访问的 LLM 模型服务。 +**系统要求**：Python3.12，可访问的 LLM 模型服务。 **安装依赖**（包含 pytest、pytest-asyncio、rouge-score 等）： diff --git a/docs/mkdocs/zh/human_in_the_loop.md b/docs/mkdocs/zh/human_in_the_loop.md index 4177938b2..6cb85eb25 100644 --- a/docs/mkdocs/zh/human_in_the_loop.md +++ b/docs/mkdocs/zh/human_in_the_loop.md @@ -1,4 +1,4 @@ -# Human-In-The-Loop +# Human-In-The-Loop(HITL) 在 Agent 处理请求的过程中，某些场景需要引入人工判断或调整，以提高任务完成的准确率。例如： - 风险操作审批：当 Agent 生成 SQL 或 Shell 脚本时，是否执行通常需要人工审批。以命令执行为例：如果人工同意，则拉起 terminal 执行并将结果回传给 Agent；如果不同意，则说明命令可能有问题，需要 Agent 重新生成替代命令。 @@ -434,4 +434,4 @@ async def run_human_in_loop_agent(): 完整的示例代码请参考： - LlmAgent：[examples/llmagent_with_human_in_the_loop/README.md](../../../examples/llmagent_with_human_in_the_loop/README.md) -- LangGraphAgent：[examples/langgraphagent_with_human_in_the_loop/README.md](../../../examples/langgraphagent_with_human_in_the_loop/README.md) +- LangGraphAgent：[examples/langgraph_agent_with_HITL/README.md](../../../examples/langgraph_agent_with_HITL/README.md) diff --git a/docs/mkdocs/zh/skill.md b/docs/mkdocs/zh/skill.md index d217ef962..5caa54a09 100644 --- a/docs/mkdocs/zh/skill.md +++ b/docs/mkdocs/zh/skill.md @@ -61,7 +61,7 @@ skills/ ### 1) 要求 -- Python 3.12 +- Python3.12 - 模型提供商的 API 密钥（兼容 OpenAI） - 可选 Docker（用于容器执行器） diff --git a/examples/a2a/README.md b/examples/a2a/README.md index 9c45540c0..6e666085c 100644 --- a/examples/a2a/README.md +++ b/examples/a2a/README.md @@ -11,33 +11,28 @@ ## 环境要求 -- Python 3.12 -- 已安装项目依赖 +- Python3.10+，推荐 Python3.12 -## 运行步骤 - -### 1. 安装依赖 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[a2a]" source .venv/bin/activate -pip3 install -e '.[a2a]' -pip3 install a2a-sdk python-dotenv ``` -### 2. 配置环境变量 +## 运行步骤 + +### 配置环境变量 在 [examples/a2a/.env](./.env) 中设置（也可通过 export）： -```bash -TRPC_AGENT_API_KEY=... -TRPC_AGENT_BASE_URL=... -TRPC_AGENT_MODEL_NAME=... -``` +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` -### 3. 启动服务端 +### 启动服务端 ```bash cd examples/a2a @@ -49,7 +44,7 @@ python3 run_server.py - API：`http://127.0.0.1:18081` - Agent Card：`http://127.0.0.1:18081/.well-known/agent.json` -### 4. 启动客户端 +### 启动客户端 新开终端执行： diff --git a/examples/a2a_with_cancel/README.md b/examples/a2a_with_cancel/README.md index 6e4ab3e7d..6401d9e68 100644 --- a/examples/a2a_with_cancel/README.md +++ b/examples/a2a_with_cancel/README.md @@ -95,36 +95,30 @@ a2a_svc = TrpcA2aAgentService( 建议两者配置相同的超时时间。 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 -- 已安装项目依赖 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[a2a]" source .venv/bin/activate -pip3 install -e '.[a2a]' ``` -### 环境变量要求 +## 运行步骤 -在 [examples/a2a_with_cancel/.env](./.env) 中设置（也可通过 export）： +### 配置环境变量 -```bash -TRPC_AGENT_API_KEY=... -TRPC_AGENT_BASE_URL=... -TRPC_AGENT_MODEL_NAME=... -``` +在 [examples/a2a_with_cancel/.env](./.env) 中设置（也可通过 export）： -### 运行步骤 +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` -#### 1. 启动服务端 +### 启动服务端 ```bash cd examples/a2a_with_cancel @@ -136,7 +130,7 @@ python3 run_server.py - API：`http://127.0.0.1:18082` - Agent Card：`http://127.0.0.1:18082/.well-known/agent.json` -#### 2. 启动客户端（新开终端） +#### 启动客户端（新开终端） ```bash cd examples/a2a_with_cancel diff --git a/examples/agent_tools/README.md b/examples/agent_tools/README.md index d9e57a197..612bfd061 100644 --- a/examples/agent_tools/README.md +++ b/examples/agent_tools/README.md @@ -56,23 +56,22 @@ content_processor (LlmAgent) — 主 Agent - `function_call`（工具调用，即主 Agent 调用翻译 AgentTool） - `function_response`（工具返回，即翻译 Agent 的回复结果） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/agent_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/agui/README.md b/examples/agui/README.md index 0a5939456..aa7be094e 100644 --- a/examples/agui/README.md +++ b/examples/agui/README.md @@ -57,24 +57,23 @@ weather_agent (LlmAgent) - `Tool result` - `Assistant` 最终文本 -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.10+，推荐 Python3.12 - Node.js 18+ -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[ag-ui]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/agui/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/agui_with_cancel/README.md b/examples/agui_with_cancel/README.md index 8765559ad..a727bd40d 100644 --- a/examples/agui_with_cancel/README.md +++ b/examples/agui_with_cancel/README.md @@ -64,23 +64,22 @@ weather_agent_with_cancel (LlmAgent) |------|--------|------| | `cancel_wait_timeout` | 3.0 | 等待 Cancel 操作完成的超时时间（秒）。如果此值配置不当，Cancel 操作可能无法成功执行，导致流式文本无法保存到会话中。 | -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.10+，推荐 Python3.12 - Node.js 18+ -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[ag-ui]" source .venv/bin/activate -pip3 install -e '.[ag-ui]' ``` +## 运行步骤 + ### 环境变量要求 在 [examples/agui_with_cancel/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent/README.md b/examples/claude_agent/README.md index 26069f2f1..1cfabe836 100644 --- a/examples/claude_agent/README.md +++ b/examples/claude_agent/README.md @@ -53,23 +53,22 @@ claude_weather_agent (ClaudeAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.10+，推荐 Python3.12 ### 安装步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e '.[agent-claude]' ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/claude_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent_with_cancel/README.md b/examples/claude_agent_with_cancel/README.md index 2b3b0ccf9..310144c8c 100644 --- a/examples/claude_agent_with_cancel/README.md +++ b/examples/claude_agent_with_cancel/README.md @@ -58,23 +58,22 @@ claude_weather_agent_with_cancel (ClaudeAgent) - 每个场景的第 2 轮对话发送 `"what happens?"`，验证 Agent 能读取之前的 Session 上下文 - 使用 `AgentCancelledEvent` 检测取消事件并优雅退出事件循环 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e '.[agent-claude]' ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/claude_agent_with_cancel/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent_with_code_writer/README.md b/examples/claude_agent_with_code_writer/README.md index 49a9ecb92..d0875e2af 100644 --- a/examples/claude_agent_with_code_writer/README.md +++ b/examples/claude_agent_with_code_writer/README.md @@ -57,20 +57,17 @@ code_writing_agent (ClaudeAgent) - `function_response`（工具返回） - 资源清理链路：`runner.close()` → `agent.destroy()` → `cleanup_claude()` -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e ".[agent-claude]" ``` 安装 Claude Code CLI： @@ -79,7 +76,9 @@ pip3 install -e ".[agent-claude]" npm install -g @anthropic-ai/claude-code ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/claude_agent_with_code_writer/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent_with_skills/README.md b/examples/claude_agent_with_skills/README.md index f5d76eb0b..10ecd804e 100644 --- a/examples/claude_agent_with_skills/README.md +++ b/examples/claude_agent_with_skills/README.md @@ -65,22 +65,21 @@ travel_planner (ClaudeAgent) - `function_call`（工具调用 / Skill 调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e '.[agent-claude]' ``` +## 运行步骤 + ### Skill 前置配置 1. 在项目目录或根目录（`~`）创建 `.claude/skills` 目录： @@ -89,7 +88,7 @@ pip3 install -e '.[agent-claude]' 2. 在 `skills` 目录下创建 Skill 子目录（如 `traver_helper`），并在其中编写 `SKILL.md` 3. Skill 格式参考：[Claude Agent SDK Skills 文档](https://platform.claude.com/docs/zh-CN/agents-and-tools/agent-skills/overview#skill) -### 环境变量要求 +### 配置环境变量 在 [examples/claude_agent_with_skills/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent_with_streaming_tool/README.md b/examples/claude_agent_with_streaming_tool/README.md index c65ccc868..3039cdb71 100644 --- a/examples/claude_agent_with_streaming_tool/README.md +++ b/examples/claude_agent_with_streaming_tool/README.md @@ -56,23 +56,22 @@ claude_streaming_file_writer (ClaudeAgent) - 监听 Claude SDK 的 `content_block_start` / `content_block_delta` 事件 - 仅当工具名在流式集合中时，才发射带有 `tool_streaming_args` 的 Event，否则跳过 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e '.[agent-claude]' ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/claude_agent_with_streaming_tool/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/claude_agent_with_travel_planner/README.md b/examples/claude_agent_with_travel_planner/README.md index 0657f2117..d40017fee 100644 --- a/examples/claude_agent_with_travel_planner/README.md +++ b/examples/claude_agent_with_travel_planner/README.md @@ -58,20 +58,17 @@ travel_planner (ClaudeAgent) - `function_response`（工具返回） - 退出时依次执行 `runner.close()` → `agent.destroy()` → `cleanup_claude()` 清理资源 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e ".[agent-claude]" ``` 安装 Claude Code CLI： @@ -89,7 +86,9 @@ curl -LsSf https://astral.sh/uv/install.sh | sh uv pip install duckduckgo-mcp-server ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/claude_agent_with_travel_planner/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/code_executors/README.md b/examples/code_executors/README.md index c42ec31db..6c8e533aa 100644 --- a/examples/code_executors/README.md +++ b/examples/code_executors/README.md @@ -56,26 +56,24 @@ code_assistant (LlmAgent) - `code_execution_result`（代码执行结果） - `function_call`（工具调用） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 -- 若使用 `ContainerCodeExecutor`，需安装 Docker 并确保 Docker daemon 正在运行 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 -在 `examples/code_executors/.env` 中配置（或通过 `export`）： +在 [examples/code_executors/.env](./.env) 中设置（也可通过 export）： - `TRPC_AGENT_API_KEY` - `TRPC_AGENT_BASE_URL` diff --git a/examples/dsl/classifier_mcp/README.md b/examples/dsl/classifier_mcp/README.md index 1343debd9..367d026b6 100644 --- a/examples/dsl/classifier_mcp/README.md +++ b/examples/dsl/classifier_mcp/README.md @@ -65,25 +65,23 @@ classifier_mcp_example (GraphAgent) - 通过 `ModelExecutionMetadata.from_event(event)` 打印模型执行状态 - `event.partial=True` 时打印流式文本分片 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv -source .venv/bin/activate -pip3 install -e . +./buid.sh uv "dev,graph" ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 -在 `examples/dsl/classifier_mcp/.env` 中配置（或通过 `export`）： +在 [examples/dsl/classifier_mcp/.env](./.env) 中配置（或通过 `export`）： - `MODEL1_NAME` / `MODEL1_API_KEY` / `MODEL1_BASE_URL`（Classifier Agent 模型） - `MODEL2_NAME` / `MODEL2_API_KEY` / `MODEL2_BASE_URL`（Simple Math Agent 模型） diff --git a/examples/dynamic_subagent/README.md b/examples/dynamic_subagent/README.md index c7b5d5370..f644f554c 100644 --- a/examples/dynamic_subagent/README.md +++ b/examples/dynamic_subagent/README.md @@ -9,9 +9,37 @@ 无论哪种模式，子 Agent 的工具面始终在代码定义的能力边界内，LLM 只能缩小、不可越界。 -## 运行 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/dynamic_subagent/.env](./.env) 中设置（也可通过 export）： ```bash +TRPC_AGENT_API_KEY=... +TRPC_AGENT_BASE_URL=... +TRPC_AGENT_MODEL_NAME=... +``` + +### 运行命令 + +```bash + +cd examples/dynamic_subagent + # minimal（默认）—— 父 Agent 与子 Agent 共享工具 python run_agent.py diff --git a/examples/evaluation/callbacks/README.md b/examples/evaluation/callbacks/README.md index 91d725c52..f307e333f 100644 --- a/examples/evaluation/callbacks/README.md +++ b/examples/evaluation/callbacks/README.md @@ -10,7 +10,7 @@ ## 环境要求 -Python 3.10+。需配置 `TRPC_AGENT_API_KEY` 等环境变量（同 quickstart）。 +Python3.10+。需配置 `TRPC_AGENT_API_KEY` 等环境变量（同 quickstart）。 ## 运行 diff --git a/examples/evaluation/context_messages/README.md b/examples/evaluation/context_messages/README.md index 76bd75c55..7f1653d6c 100644 --- a/examples/evaluation/context_messages/README.md +++ b/examples/evaluation/context_messages/README.md @@ -10,7 +10,7 @@ ## 环境要求 -Python 3.10+。需配置 `TRPC_AGENT_API_KEY` 等环境变量（同 quickstart）。 +Python3.10+。需配置 `TRPC_AGENT_API_KEY` 等环境变量（同 quickstart）。 ## 运行 diff --git a/examples/evaluation/pass_at_k/README.md b/examples/evaluation/pass_at_k/README.md index 71b2bb627..20088ba99 100644 --- a/examples/evaluation/pass_at_k/README.md +++ b/examples/evaluation/pass_at_k/README.md @@ -10,7 +10,7 @@ ## 环境要求 -Python 3.10+。环境变量同 quickstart（`TRPC_AGENT_API_KEY` 等）。 +Python3.10+。环境变量同 quickstart（`TRPC_AGENT_API_KEY` 等）。 ## 运行 diff --git a/examples/evaluation/quickstart/README.md b/examples/evaluation/quickstart/README.md index 6d709bd99..3e092cb9f 100644 --- a/examples/evaluation/quickstart/README.md +++ b/examples/evaluation/quickstart/README.md @@ -9,7 +9,7 @@ ## 环境要求 -Python 3.10+（建议 3.12） +Python3.10+（建议 3.12） ## 环境变量 diff --git a/examples/evaluation/trace_mode/README.md b/examples/evaluation/trace_mode/README.md index 3b1ce6389..a38ff2185 100644 --- a/examples/evaluation/trace_mode/README.md +++ b/examples/evaluation/trace_mode/README.md @@ -10,7 +10,7 @@ ## 环境要求 -Python 3.10+。Trace 模式不跑模型推理，但框架仍会加载 agent 模块；若未配置 `TRPC_AGENT_API_KEY`，加载可能报错，可按需配置或仅用於查看結構。 +Python3.10+。Trace 模式不跑模型推理，但框架仍会加载 agent 模块；若未配置 `TRPC_AGENT_API_KEY`，加载可能报错，可按需配置或仅用於查看結構。 ## 运行 diff --git a/examples/evaluation/webui/README.md b/examples/evaluation/webui/README.md index fea2ba30b..09f0dec14 100644 --- a/examples/evaluation/webui/README.md +++ b/examples/evaluation/webui/README.md @@ -9,7 +9,7 @@ ## 环境要求 -Python 3.10+（建议 3.12） +Python3.10+（建议 3.12） ## 环境变量 diff --git a/examples/fastapi_server/README.md b/examples/fastapi_server/README.md index da2db1126..a3a5699aa 100644 --- a/examples/fastapi_server/README.md +++ b/examples/fastapi_server/README.md @@ -105,23 +105,23 @@ def create_agent() -> LlmAgent: - **`done`**：流结束，正常退出（data 为 `null`） - **`error`**：流中发生异常（data 为错误信息字符串） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . +pip3 install fastapi ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/fastapi_server/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/file_tools/README.md b/examples/file_tools/README.md index cfbe320d6..a7ad46e5a 100644 --- a/examples/file_tools/README.md +++ b/examples/file_tools/README.md @@ -59,23 +59,22 @@ file_assistant (LlmAgent) - `function_response`（工具返回结果） - 执行结束后打印最终文件内容，并自动清理工作目录 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/file_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/filter_with_agent/README.md b/examples/filter_with_agent/README.md index ebf1d6edc..76865c916 100644 --- a/examples/filter_with_agent/README.md +++ b/examples/filter_with_agent/README.md @@ -56,23 +56,22 @@ weather_agent (LlmAgent) - 通过 `filters_name=["agent_filter"]` 关联已注册的 Filter - 同时设置 `before_agent_callback` 和 `after_agent_callback` 两个 Callback 钩子 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/filter_with_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/filter_with_model/README.md b/examples/filter_with_model/README.md index 7931277fb..6ee0f3a4b 100644 --- a/examples/filter_with_model/README.md +++ b/examples/filter_with_model/README.md @@ -54,23 +54,22 @@ weather_agent (LlmAgent) - 在 `OpenAIModel` 初始化时通过 `filters_name=["model_filter"]` 指定要应用的 Filter 名称 - 框架在运行时自动查找已注册的 Filter 并组装到调用链中 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/filter_with_model/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/filter_with_tool/README.md b/examples/filter_with_tool/README.md index 4a6d1c9c6..91e4f7afa 100644 --- a/examples/filter_with_tool/README.md +++ b/examples/filter_with_tool/README.md @@ -54,23 +54,22 @@ assistant (LlmAgent) - `FunctionTool(get_weather_report, filters_name=["tool_filter"])`：将工具与已注册的 Filter 关联 - 工具调用时执行顺序：`before_tool_callback → ToolFilter.run(前置) → 工具执行 → ToolFilter.run(后置) → after_tool_callback` -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/filter_with_tool/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/function_tools/README.md b/examples/function_tools/README.md index 04b00629f..68c6173ef 100644 --- a/examples/function_tools/README.md +++ b/examples/function_tools/README.md @@ -60,23 +60,22 @@ function_tool_demo_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/function_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/goal_tools/README.md b/examples/goal_tools/README.md index ffd655245..8c78a7117 100644 --- a/examples/goal_tools/README.md +++ b/examples/goal_tools/README.md @@ -2,19 +2,34 @@ 演示 **Goal 工具族**（`create_goal` / `get_goal` / `update_goal`）：为会话设置一个持久目标，目标未完成前 Agent 应继续执行，而不是过早给出最终回复。示例同时挂载 `Bash` / `Write` / `Read` 完成真实的多步文件任务。 -## 快速开始 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 ```bash -# 在项目根目录安装 +git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv && source .venv/bin/activate -pip3 install -e . +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 -# 配置模型（examples/goal_tools/.env） -TRPC_AGENT_API_KEY=your-api-key -TRPC_AGENT_BASE_URL=your-base-url -TRPC_AGENT_MODEL_NAME=your-model-name +在 [examples/goal_tools/.env](./.env) 中设置（也可通过 export）： +```bash +TRPC_AGENT_API_KEY=... +TRPC_AGENT_BASE_URL=... +TRPC_AGENT_MODEL_NAME=... +``` + +### 运行命令 + +```bash # 运行 cd examples/goal_tools python3 run_agent.py diff --git a/examples/graph/README.md b/examples/graph/README.md index db74e788d..be82e9017 100644 --- a/examples/graph/README.md +++ b/examples/graph/README.md @@ -112,23 +112,22 @@ graph TD - `after_node` 回调记录执行时间，写入 `node_execution_history` 列表 - `format_output` 节点读取 `node_execution_history`，生成完整的执行流程报告 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/graph/.env](./.env) 中配置（或通过 `export`）： @@ -136,7 +135,7 @@ pip3 install -e . - `TRPC_AGENT_BASE_URL` - `TRPC_AGENT_MODEL_NAME` -#### 启用知识搜索分支（可选） +### 启用知识搜索分支（可选） 1. 在 `run_agent.py` 中设置 `ENABLE_KNOWLEDGE = True` 2. 在 `.env` 中额外配置 TRAG 环境变量： diff --git a/examples/graph_multi_turns/README.md b/examples/graph_multi_turns/README.md index 4a26faeac..9fc23d727 100644 --- a/examples/graph_multi_turns/README.md +++ b/examples/graph_multi_turns/README.md @@ -57,23 +57,22 @@ graph_multi_turns (GraphAgent) - 通过 `runner.run_async(...)` 消费事件流，打印节点生命周期（`Node start` / `Node done`）、模型调用（`Model start` / `Model done`）等日志 - 从 Session 状态中读取 `STATE_KEY_LAST_RESPONSE` 获取格式化后的最终输出 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/graph_multi_turns/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/graph_with_interrupt/README.md b/examples/graph_with_interrupt/README.md index 9575608ff..b42cb0553 100644 --- a/examples/graph_with_interrupt/README.md +++ b/examples/graph_with_interrupt/README.md @@ -77,23 +77,22 @@ graph TD - 通过 `NodeExecutionMetadata` / `ModelExecutionMetadata` / `ToolExecutionMetadata` 解析生命周期事件 - 当收到 `LongRunningEvent` 时记录中断信息，随后用 `FunctionResponse` 构造 resume 消息继续执行 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/graph_with_interrupt/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_custom_components/README.md b/examples/knowledge_with_custom_components/README.md index 2b3087513..63614112a 100644 --- a/examples/knowledge_with_custom_components/README.md +++ b/examples/knowledge_with_custom_components/README.md @@ -61,26 +61,25 @@ LangchainKnowledge (x3 实例) - 实现 `from_documents` 类方法，支持与 VectorStore 配合使用时的工厂创建模式 - 在 `agent.py` 的 `create_retriever_knowledge()` 中，直接传入预构造的 `Document` 列表，不依赖 Embedding 模型 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" source .venv/bin/activate -pip3 install -e ".[knowledge]" ``` > **注意**：本示例依赖 `langchain-text-splitters`、`langchain-community`、`langchain-huggingface` 等包， -> 必须使用 `pip3 install -e ".[knowledge]"` 安装 knowledge 可选依赖，否则会报 `ModuleNotFoundError`。 +> 必须使用 `./build.sh "[knowledge,knowledge-hf]"` 安装 knowledge 与 Hugging Face 可选依赖，否则会报 `ModuleNotFoundError`。 + +## 运行步骤 -### 环境变量要求 +### 配置环境变量 在 [examples/knowledge_with_custom_components/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_documentloader/README.md b/examples/knowledge_with_documentloader/README.md index 5fa28b0b4..b9504deaf 100644 --- a/examples/knowledge_with_documentloader/README.md +++ b/examples/knowledge_with_documentloader/README.md @@ -57,26 +57,17 @@ documentloader_agent (LlmAgent) - Agent 接收到用户问题后，自动调用 `simple_search` 检索知识库，结合检索结果生成回答 - 流式事件中区分并打印 `function_call`（工具调用）与 `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" source .venv/bin/activate -pip3 install -e ".[knowledge]" -``` - -安装 DocumentLoader 相关依赖： - -```bash -pip3 install langchain-community langchain-huggingface sentence-transformers ``` 如需使用 `PyPDFLoader`，还需安装： @@ -93,15 +84,15 @@ pip3 install unstructured | 依赖包 | 说明 | |---|---| -| `langchain-community` | 提供 `TextLoader`、`PyPDFLoader`、`UnstructuredMarkdownLoader` 等文档加载器 | -| `langchain-huggingface` | 提供 `HuggingFaceEmbeddings` 向量嵌入模型接口 | | `sentence-transformers` | HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 | | `pypdf` | `PyPDFLoader` 的底层依赖，用于解析 PDF 文件 | | `unstructured` | `UnstructuredMarkdownLoader` 的底层依赖，用于解析 Markdown 文件 | > 首次运行时会自动从 HuggingFace Hub 下载 `BAAI/bge-small-en-v1.5` 嵌入模型，请确保网络可访问 huggingface.co。 -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/knowledge_with_documentloader/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_prompt_template/README.md b/examples/knowledge_with_prompt_template/README.md index 5fdab187b..75b935a97 100644 --- a/examples/knowledge_with_prompt_template/README.md +++ b/examples/knowledge_with_prompt_template/README.md @@ -55,35 +55,25 @@ rag_agent_{template_type} (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" source .venv/bin/activate -pip3 install -e ".[knowledge]" -``` -本示例还依赖 Langchain 社区组件和 HuggingFace 向量嵌入模型，需要额外安装： - -```bash -pip3 install langchain-community langchain-huggingface sentence-transformers +# HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 +pip3 install sentence-transformers ``` -| 依赖包 | 说明 | -|---|---| -| `langchain-community` | 提供 `TextLoader` 等文档加载器 | -| `langchain-huggingface` | 提供 `HuggingFaceEmbeddings` 向量嵌入模型接口 | -| `sentence-transformers` | HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 | +## 运行步骤 -### 环境变量要求 +### 配置环境变量 在 [examples/knowledge_with_prompt_template/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_rag_agent/README.md b/examples/knowledge_with_rag_agent/README.md index 09eb14f22..49d06e0f1 100644 --- a/examples/knowledge_with_rag_agent/README.md +++ b/examples/knowledge_with_rag_agent/README.md @@ -65,37 +65,24 @@ rag_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" source .venv/bin/activate -pip3 install -e ".[knowledge]" ``` -安装 RAG 相关额外依赖： - -```bash -pip3 install langchain-community langchain-huggingface sentence-transformers -``` - -| 依赖包 | 说明 | -|---|---| -| `langchain-community` | 提供 `TextLoader` 等文档加载器 | -| `langchain-huggingface` | 提供 `HuggingFaceEmbeddings` 向量嵌入模型接口 | -| `sentence-transformers` | HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 | - > 首次运行时会自动从 HuggingFace Hub 下载 `BAAI/bge-small-en-v1.5` 嵌入模型，请确保网络可访问 huggingface.co。 -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/knowledge_with_rag_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_searchtool_rag_agent/README.md b/examples/knowledge_with_searchtool_rag_agent/README.md index 5e5ded6e6..0331f1be4 100644 --- a/examples/knowledge_with_searchtool_rag_agent/README.md +++ b/examples/knowledge_with_searchtool_rag_agent/README.md @@ -61,37 +61,26 @@ rag_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" source .venv/bin/activate -pip3 install -e ".[knowledge]" +# HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 +pip3 install sentence-transformers ``` -安装 RAG 相关依赖： - -```bash -pip3 install langchain-community langchain-huggingface sentence-transformers -``` - -| 依赖包 | 说明 | -|---|---| -| `langchain-community` | 提供 `TextLoader` 等文档加载器 | -| `langchain-huggingface` | 提供 `HuggingFaceEmbeddings` 向量嵌入模型接口 | -| `sentence-transformers` | HuggingFace 嵌入模型的底层依赖，用于加载和运行嵌入模型 | - > 首次运行时会自动从 HuggingFace Hub 下载 `BAAI/bge-small-en-v1.5` 嵌入模型，请确保网络可访问 huggingface.co。 -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/knowledge_with_searchtool_rag_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/knowledge_with_vectorstore/README.md b/examples/knowledge_with_vectorstore/README.md index f06555d16..c974b20ce 100644 --- a/examples/knowledge_with_vectorstore/README.md +++ b/examples/knowledge_with_vectorstore/README.md @@ -56,20 +56,18 @@ rag_agent (LlmAgent) - `run_agent.py` 执行流程：加载 `.env` → 调用 `rag.create_vectorstore_from_document()` 构建向量库 → 创建 `Runner` 发起对话 - 使用 `runner.run_async(...)` 消费事件流，区分并打印 `function_call`（工具调用）与 `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[knowledge,knowledge-hf]" + source .venv/bin/activate -pip3 install -e . ``` 根据选择的向量数据库后端安装 RAG 相关依赖： @@ -77,24 +75,26 @@ pip3 install -e . **PGVector：** ```bash -pip3 install langchain-community langchain-huggingface sentence-transformers langchain-postgres +pip3 install langchain-postgres ``` **Elasticsearch：** ```bash -pip3 install langchain-community langchain-huggingface sentence-transformers langchain-elasticsearch +pip3 install langchain-elasticsearch ``` **腾讯云向量数据库：** ```bash -pip3 install langchain-community tcvectordb +pip3 install tcvectordb ``` > 使用 PGVector / Elasticsearch 时，首次运行会自动从 HuggingFace Hub 下载 `BAAI/bge-small-en-v1.5` 嵌入模型，请确保网络可访问 HuggingFace。 -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/knowledge_with_vectorstore/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/langchain_tools/README.md b/examples/langchain_tools/README.md index 8449de206..7a12a2fb4 100644 --- a/examples/langchain_tools/README.md +++ b/examples/langchain_tools/README.md @@ -52,24 +52,22 @@ langchain_tavily_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[langchain_tool]" source .venv/bin/activate -pip3 install -e . -pip3 install langchain-tavily ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/langchain_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/langgraph_agent/README.md b/examples/langgraph_agent/README.md index 81367f6b2..4753245bc 100644 --- a/examples/langgraph_agent/README.md +++ b/examples/langgraph_agent/README.md @@ -59,23 +59,22 @@ simple_langgraph_agent (LangGraphAgent) - `function_response`（工具返回） - 同一 `session_id` 下连续执行 4 轮查询，验证上下文记忆能力 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/langgraph_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/langgraph_agent_with_HITL/.env b/examples/langgraph_agent_with_HITL/.env new file mode 100644 index 000000000..734d3d6a1 --- /dev/null +++ b/examples/langgraph_agent_with_HITL/.env @@ -0,0 +1,4 @@ +# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME +TRPC_AGENT_API_KEY=sk-WxWSgB75Z8cbcByxdLGlhhfXp2StI9xGBqy5GLaFM5i0mJo9 +TRPC_AGENT_BASE_URL=http://03-llm.woa.com/glm5/v1 +TRPC_AGENT_MODEL_NAME=glm-5.0-w4afp8 diff --git a/examples/langgraphagent_with_human_in_the_loop/README.md b/examples/langgraph_agent_with_HITL/README.md similarity index 86% rename from examples/langgraphagent_with_human_in_the_loop/README.md rename to examples/langgraph_agent_with_HITL/README.md index 74e97c97f..77a7d3eb9 100644 --- a/examples/langgraphagent_with_human_in_the_loop/README.md +++ b/examples/langgraph_agent_with_HITL/README.md @@ -1,4 +1,4 @@ -# LangGraph Agent Human-in-the-Loop 示例 +# LangGraph Agent Human-in-the-Loop(HITL) 示例 本示例演示如何基于 `LangGraphAgent` 构建一个需要人工审批的数据库操作助手，并验证 `LangGraph StateGraph + interrupt() + Command 路由` 的 Human-in-the-Loop 核心链路是否正常工作。 @@ -29,11 +29,11 @@ human_in_loop_langgraph_agent (LangGraphAgent) 关键文件： -- [examples/langgraphagent_with_human_in_the_loop/agent/agent.py](./agent/agent.py)：`StateGraph` 图定义、节点构建、`LangGraphAgent` 创建 -- [examples/langgraphagent_with_human_in_the_loop/agent/tools.py](./agent/tools.py)：数据库操作工具（`@tool` + `@langgraph_tool_node`） -- [examples/langgraphagent_with_human_in_the_loop/agent/prompts.py](./agent/prompts.py)：Agent 指令提示词 -- [examples/langgraphagent_with_human_in_the_loop/agent/config.py](./agent/config.py)：环境变量读取 -- [examples/langgraphagent_with_human_in_the_loop/run_agent.py](./run_agent.py)：测试入口，驱动执行与审批恢复 +- [examples/langgraph_agent_with_HITL/agent/agent.py](./agent/agent.py)：`StateGraph` 图定义、节点构建、`LangGraphAgent` 创建 +- [examples/langgraph_agent_with_HITL/agent/tools.py](./agent/tools.py)：数据库操作工具（`@tool` + `@langgraph_tool_node`） +- [examples/langgraph_agent_with_HITL/agent/prompts.py](./agent/prompts.py)：Agent 指令提示词 +- [examples/langgraph_agent_with_HITL/agent/config.py](./agent/config.py)：环境变量读取 +- [examples/langgraph_agent_with_HITL/run_agent.py](./run_agent.py)：测试入口，驱动执行与审批恢复 ## 关键代码解释 @@ -58,25 +58,24 @@ human_in_loop_langgraph_agent (LangGraphAgent) - 捕获到 `LongRunningEvent` 后模拟人工审批，构造 `FunctionResponse` 携带审批决策 - 通过 `resume_content` 再次调用 `run_invocation` 恢复图执行 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 -在 [examples/langgraphagent_with_human_in_the_loop/.env](./.env) 中配置（或通过 `export`）： +在 [examples/langgraph_agent_with_HITL/.env](./.env) 中配置（或通过 `export`）： - `TRPC_AGENT_API_KEY` - `TRPC_AGENT_BASE_URL` @@ -85,7 +84,7 @@ pip3 install -e . ### 运行命令 ```bash -cd examples/langgraphagent_with_human_in_the_loop +cd examples/langgraph_agent_with_HITL python3 run_agent.py ``` diff --git a/examples/langgraphagent_with_human_in_the_loop/agent/__init__.py b/examples/langgraph_agent_with_HITL/agent/__init__.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/agent/__init__.py rename to examples/langgraph_agent_with_HITL/agent/__init__.py diff --git a/examples/langgraphagent_with_human_in_the_loop/agent/agent.py b/examples/langgraph_agent_with_HITL/agent/agent.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/agent/agent.py rename to examples/langgraph_agent_with_HITL/agent/agent.py diff --git a/examples/langgraphagent_with_human_in_the_loop/agent/config.py b/examples/langgraph_agent_with_HITL/agent/config.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/agent/config.py rename to examples/langgraph_agent_with_HITL/agent/config.py diff --git a/examples/langgraphagent_with_human_in_the_loop/agent/prompts.py b/examples/langgraph_agent_with_HITL/agent/prompts.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/agent/prompts.py rename to examples/langgraph_agent_with_HITL/agent/prompts.py diff --git a/examples/langgraphagent_with_human_in_the_loop/agent/tools.py b/examples/langgraph_agent_with_HITL/agent/tools.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/agent/tools.py rename to examples/langgraph_agent_with_HITL/agent/tools.py diff --git a/examples/langgraphagent_with_human_in_the_loop/run_agent.py b/examples/langgraph_agent_with_HITL/run_agent.py similarity index 100% rename from examples/langgraphagent_with_human_in_the_loop/run_agent.py rename to examples/langgraph_agent_with_HITL/run_agent.py diff --git a/examples/langgraph_agent_with_cancel/README.md b/examples/langgraph_agent_with_cancel/README.md index ef3827ac5..601b5f354 100644 --- a/examples/langgraph_agent_with_cancel/README.md +++ b/examples/langgraph_agent_with_cancel/README.md @@ -56,23 +56,22 @@ calculator_agent_with_cancel (LangGraphAgent) - 每个场景包含 2 轮查询：第 1 轮触发取消，第 2 轮询问 "what happened?" 验证会话状态完整性 - 通过 `AgentCancelledEvent` 识别取消事件，区分正常结束与取消退出 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[graph]" source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/langgraph_agent_with_cancel/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/langgraphagent_with_human_in_the_loop/.env b/examples/langgraphagent_with_human_in_the_loop/.env deleted file mode 100644 index dc791393a..000000000 --- a/examples/langgraphagent_with_human_in_the_loop/.env +++ /dev/null @@ -1,4 +0,0 @@ -# Set TRPC_AGENT_API_KEY、TRPC_AGENT_BASE_URL、TRPC_AGENT_MODEL_NAME -TRPC_AGENT_API_KEY=your-api-key -TRPC_AGENT_BASE_URL=your-base-url -TRPC_AGENT_MODEL_NAME=your-model-name diff --git a/examples/litellm/README.md b/examples/litellm/README.md index a4aa50683..4bb824202 100644 --- a/examples/litellm/README.md +++ b/examples/litellm/README.md @@ -58,23 +58,22 @@ weather_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/litellm/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent/README.md b/examples/llmagent/README.md index 5ec5f1947..86c292d59 100644 --- a/examples/llmagent/README.md +++ b/examples/llmagent/README.md @@ -55,23 +55,22 @@ weather_agent (LlmAgent) - `function_call`（工具调用） - `function_response`（工具返回） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_branch_filtering/README.md b/examples/llmagent_with_branch_filtering/README.md index be8b9b986..b332063d6 100644 --- a/examples/llmagent_with_branch_filtering/README.md +++ b/examples/llmagent_with_branch_filtering/README.md @@ -66,20 +66,17 @@ CustomerService (EXACT - always) | DatabaseExpert | `CustomerService.TechnicalSupport.DatabaseExpert` | 全部 | CS + TS + DB | 仅自身 | | BillingSupport | `CustomerService.BillingSupport` | 全部 | CS + BS | 仅自身 | -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` ### 环境变量要求 diff --git a/examples/llmagent_with_cancel/README.md b/examples/llmagent_with_cancel/README.md index 32ed5e666..00304bf8c 100644 --- a/examples/llmagent_with_cancel/README.md +++ b/examples/llmagent_with_cancel/README.md @@ -51,23 +51,22 @@ weather_agent (LlmAgent) - 输出统一取消提示：`Run was cancelled` - 不中断进程，继续后续 Query 验证会话状态 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_cancel/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_custom_agent/README.md b/examples/llmagent_with_custom_agent/README.md index 4113533a9..0b91f2dba 100644 --- a/examples/llmagent_with_custom_agent/README.md +++ b/examples/llmagent_with_custom_agent/README.md @@ -56,23 +56,22 @@ smart_document_processor (Custom BaseAgent) - `simple` 文档跳过质量校验（性能优先） - 校验反馈写入 `quality_feedback`，并输出是否通过的阶段日志 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_custom_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_custom_prompt/README.md b/examples/llmagent_with_custom_prompt/README.md index 998e03e66..d0ae6d9bf 100644 --- a/examples/llmagent_with_custom_prompt/README.md +++ b/examples/llmagent_with_custom_prompt/README.md @@ -50,23 +50,22 @@ Coordinator (LlmAgent) - **Scenario 2**：关闭名称注入（仅保留默认转发） - **Scenario 3**：名称注入 + 自定义转发提示 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_custom_prompt/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_human_in_the_loop/README.md b/examples/llmagent_with_human_in_the_loop/README.md index 885595ca9..22adeb00f 100644 --- a/examples/llmagent_with_human_in_the_loop/README.md +++ b/examples/llmagent_with_human_in_the_loop/README.md @@ -49,23 +49,22 @@ human_in_loop_agent (LlmAgent) - 构造 `FunctionResponse` 作为 `resume_content` 再次调用 `run_invocation(...)` - Agent 读取审批结果后继续给出最终执行结论 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_human_in_the_loop/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_max_history_messages/README.md b/examples/llmagent_with_max_history_messages/README.md index f2ed572b1..599b34c9e 100644 --- a/examples/llmagent_with_max_history_messages/README.md +++ b/examples/llmagent_with_max_history_messages/README.md @@ -53,23 +53,22 @@ assistant (LlmAgent) - 重点观察第 4 轮是否还能提到第 1 轮信息（姓名） - 用于验证历史裁剪是否按预期生效 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_max_history_messages/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_model_create_fn/README.md b/examples/llmagent_with_model_create_fn/README.md index a61573839..b35e41bf4 100644 --- a/examples/llmagent_with_model_create_fn/README.md +++ b/examples/llmagent_with_model_create_fn/README.md @@ -50,23 +50,22 @@ weather_agent (LlmAgent) - 通过 `runner.run_async(..., run_config=run_config)` 传入 - 在控制台验证模型工厂收到该参数 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_model_create_fn/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_model_retry/README.md b/examples/llmagent_with_model_retry/README.md index 044eece92..34ace326e 100644 --- a/examples/llmagent_with_model_retry/README.md +++ b/examples/llmagent_with_model_retry/README.md @@ -101,23 +101,22 @@ async for event in runner.run_async(...): - 重试次数已耗尽。 - 流式输出已经产生内容后才发生的错误。 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.10+ - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_model_retry/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_parallal_tools/README.md b/examples/llmagent_with_parallal_tools/README.md index 279ac0121..59d0ab28c 100644 --- a/examples/llmagent_with_parallal_tools/README.md +++ b/examples/llmagent_with_parallal_tools/README.md @@ -50,23 +50,22 @@ hobby_toolset_agent (LlmAgent) - 在输出中可观测到 3 次工具调用与 3 次工具结果 - 最终由模型聚合结果生成自然语言总结 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_parallal_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/llmagent_with_prompt_cache/README.md b/examples/llmagent_with_prompt_cache/README.md index 72f3d335e..4f4a5aee3 100644 --- a/examples/llmagent_with_prompt_cache/README.md +++ b/examples/llmagent_with_prompt_cache/README.md @@ -24,23 +24,22 @@ llmagent_with_prompt_cache/ --- -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_prompt_cache/.env](./.env) 中填入凭证： diff --git a/examples/llmagent_with_schema/README.md b/examples/llmagent_with_schema/README.md index 06f33b7d7..8c7b2e60a 100644 --- a/examples/llmagent_with_schema/README.md +++ b/examples/llmagent_with_schema/README.md @@ -52,23 +52,22 @@ profile_analyzer (AgentTool) - 将画像分析 Agent 包装为 `AgentTool` - 上层 Agent 只需传入文本或结构参数，即可复用同一分析能力 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_schema/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_streaming_progress_tool/README.md b/examples/llmagent_with_streaming_progress_tool/README.md index 14e36bd21..cb401c876 100644 --- a/examples/llmagent_with_streaming_progress_tool/README.md +++ b/examples/llmagent_with_streaming_progress_tool/README.md @@ -1,54 +1,90 @@ -# Streaming Progress Tool +# Streaming Progress Tool 示例（长耗时工具实时进度流） -This example shows how to expose a **long-running tool that streams progress -events to the user in real time**, using `StreamingProgressTool`. +本示例演示如何使用 `StreamingProgressTool`，让长耗时工具在执行过程中实时向用户推送进度事件。 -The wrapped function is an `async def` generator (`async def fn(...): yield ...`). -Every `yield` is surfaced to the runner as a `partial=True` Event tagged with -`custom_metadata={"tool_progress": True, ...}`. The **last** yielded value is -*also* the final `function_response` returned to the LLM. +被包装的函数是 `async def` 生成器（`async def fn(...): yield ...`）。每次 `yield` 都会以 `partial=True` 的 Event 形式输出，并带有 `custom_metadata={"tool_progress": True, ...}`。**最后一次** `yield` 的值同时作为最终 `function_response` 返回给 LLM。 ```text -yield progress_1 --> partial Event (live) -yield progress_2 --> partial Event (live) -yield progress_3 --> partial Event (live) AND final function_response +yield progress_1 --> partial Event（实时进度） +yield progress_2 --> partial Event（实时进度） +yield progress_3 --> partial Event（实时进度）AND 最终 function_response ``` -This is different from the other two streaming-ish tools shipped with the SDK: +## 功能说明 -| Class | What gets streamed | -| --------------------------- | --------------------------------------------------- | -| `StreamingFunctionTool` | The *arguments* the LLM is generating for the call. | -| `LongRunningFunctionTool` | Nothing intermediate; just marks the call as slow. | -| **`StreamingProgressTool`** | The tool's *own* execution progress. | +- 使用 `StreamingProgressTool` 包装异步生成器工具 +- 工具执行过程中实时输出进度事件（`tool_progress`） +- 最后一次 `yield` 作为最终工具结果回传给 LLM +- 演示客户端如何过滤并打印进度事件 +- 与同类工具的区别： -## Run +| 类 | 流式内容 | +|---|---| +| `StreamingFunctionTool` | LLM 正在生成的工具**参数** | +| `LongRunningFunctionTool` | 无中间进度，仅标记调用耗时长 | +| **`StreamingProgressTool`** | 工具**自身执行进度** | + +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 ```bash -cd examples/llmagent_with_streaming_progress_tool -cp ../mcp_tools/.env .env # or write your own -# edit .env to set TRPC_AGENT_API_KEY / BASE_URL / MODEL_NAME -python run_agent.py +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate ``` -Expected output (abridged): +## 运行步骤 + +### 配置环境变量 +在 [examples/llmagent_with_streaming_progress_tool/.env](./.env) 中设置（也可通过 export）： + +```bash +TRPC_AGENT_API_KEY=... +TRPC_AGENT_BASE_URL=... +TRPC_AGENT_MODEL_NAME=... ``` + +### 启动示例 + +```bash +cd examples/llmagent_with_streaming_progress_tool +python3 run_agent.py +``` + +## 运行结果（实测） + +```text ++--------------------------------------------------------------+ +| StreamingProgressTool Demo (long-running tool) | +| | +| Watch the tool yield progress events live, then the LLM | +| summarises the final result. | ++--------------------------------------------------------------+ + +============================================================ User: Please crawl https://example.com and fetch the first 5 pages. +============================================================ +[tool-call] crawl_site({'url': 'https://example.com', 'max_pages': 5}) [crawl_site] ⏳ {'status': 'started', 'url': 'https://example.com', 'max_pages': 5} -[crawl_site] ⏳ {'status': 'fetched', 'page': 1, 'total': 5, ...} -[crawl_site] ⏳ {'status': 'fetched', 'page': 2, 'total': 5, ...} -... -[tool-result] crawl_site → {'status': 'done', 'url': '...', 'pages_fetched': 5, ...} +[crawl_site] ⏳ {'status': 'fetched', 'page': 1, 'total': 5, 'title': 'https://example.com - page 1', 'progress': 0.2} +[crawl_site] ⏳ {'status': 'fetched', 'page': 2, 'total': 5, 'title': 'https://example.com - page 2', 'progress': 0.4} +[crawl_site] ⏳ {'status': 'fetched', 'page': 3, 'total': 5, 'title': 'https://example.com - page 3', 'progress': 0.6} +[crawl_site] ⏳ {'status': 'fetched', 'page': 4, 'total': 5, 'title': 'https://example.com - page 4', 'progress': 0.8} +[crawl_site] ⏳ {'status': 'fetched', 'page': 5, 'total': 5, 'title': 'https://example.com - page 5', 'progress': 1.0} +[crawl_site] ⏳ {'status': 'done', 'url': 'https://example.com', 'pages_fetched': 5, 'titles': [...]} +[tool-result] crawl_site → {'status': 'done', 'url': 'https://example.com', 'pages_fetched': 5, ...} Assistant: I crawled example.com and fetched 5 pages. ... +------------------------------------------------------------ ``` -## How to consume progress events on the client side +## 客户端消费进度事件 -Filter on `event.partial` + `custom_metadata.tool_progress` to detect a -progress chunk. The raw value the tool yielded is available in -`custom_metadata['payload']` (for `dict`/`BaseModel` yields) and as a JSON -string in `event.content.parts[0].text` for plain-text consumers. +过滤 `event.partial` + `custom_metadata.tool_progress` 即可识别进度块。工具 `yield` 的原始值在 `custom_metadata['payload']` 中（`dict` / `BaseModel`）；纯文本场景也可读 `event.content.parts[0].text`。 ```python async for event in runner.run_async(...): @@ -56,12 +92,22 @@ async for event in runner.run_async(...): if event.partial and meta.get("tool_progress"): print(meta["tool_name"], meta.get("payload") or event.get_text()) continue - # ...handle final events as usual + # ... 按常规处理最终事件 ``` -Notes: -- Progress events are NOT persisted into session history (they are partial). -- The LLM only ever sees the **last** yielded value as the tool response. -- If a batch contains a progress-streaming tool, the framework forces - sequential tool execution to keep interim events in deterministic order, - even if the agent has `parallel_tool_calls=True`. +说明： + +- 进度事件不会写入会话历史（`partial=True`） +- LLM 只会看到**最后一次** `yield` 作为工具响应 +- 若同一批次包含进度流工具，框架会强制串行执行工具，以保证中间事件顺序确定（即使 Agent 开启了 `parallel_tool_calls=True`） + +## 文件说明 + +| 文件 | 说明 | +|---|---| +| `run_agent.py` | 示例入口（发起一次爬取请求并打印进度/结果） | +| `agent/agent.py` | Agent 定义（`LlmAgent` + `StreamingProgressTool`） | +| `agent/config.py` | 模型配置（从环境变量读取） | +| `agent/prompts.py` | Agent 提示词 | +| `agent/tools.py` | 模拟站点爬取工具（`crawl_site`） | +| `.env` | 环境变量配置文件 | diff --git a/examples/llmagent_with_streaming_tool_complex/README.md b/examples/llmagent_with_streaming_tool_complex/README.md index 63d862383..f0f434a35 100644 --- a/examples/llmagent_with_streaming_tool_complex/README.md +++ b/examples/llmagent_with_streaming_tool_complex/README.md @@ -27,23 +27,22 @@ per-test LlmAgent - 用例循环内为不同场景注册 `StreamingFunctionTool` 或混合 `ToolSet`，并打印流式片段 - 通过 `Runner` + `InMemorySessionService` 执行，观察工具参数逐步到达与执行完成 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_streaming_tool_complex/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_streaming_tool_simple/README.md b/examples/llmagent_with_streaming_tool_simple/README.md index 61c6b9fd3..6114e3f1f 100644 --- a/examples/llmagent_with_streaming_tool_simple/README.md +++ b/examples/llmagent_with_streaming_tool_simple/README.md @@ -25,23 +25,22 @@ root_agent (LlmAgent) - 使用 `Runner` 驱动 Agent，用户消息请求创建 HTML 文件 - 模型生成工具参数时触发流式事件，最终合并执行模拟写文件 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_streaming_tool_simple/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_thinking/README.md b/examples/llmagent_with_thinking/README.md index ad86cf8d0..5a7792fbc 100644 --- a/examples/llmagent_with_thinking/README.md +++ b/examples/llmagent_with_thinking/README.md @@ -27,23 +27,22 @@ root_agent (LlmAgent, thinking enabled) - `Runner` + `InMemorySessionService` 按预设问题列表循环调用 `run_async` - Agent 配置中打开思考能力，模型在工具前后组织回复 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_thinking/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_timeline_filtering/README.md b/examples/llmagent_with_timeline_filtering/README.md index 1984a520b..e4ee7c645 100644 --- a/examples/llmagent_with_timeline_filtering/README.md +++ b/examples/llmagent_with_timeline_filtering/README.md @@ -26,23 +26,22 @@ create_agent(...) (LlmAgent) - `test_scenarios` 中为每种模式构造 `Runner`，共享逻辑的三轮 `demo_queries` - `INVOCATION` 下第三轮无法看到前两轮在本会话中累积的内容（与 `out.txt` 一致） -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_timeline_filtering/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_tool_prompt/README.md b/examples/llmagent_with_tool_prompt/README.md index ff8e4c822..a6e17f6f5 100644 --- a/examples/llmagent_with_tool_prompt/README.md +++ b/examples/llmagent_with_tool_prompt/README.md @@ -26,23 +26,22 @@ root_agent (LlmAgent, tool_prompt=XML style) - Agent 配置中指定工具提示模板，引导模型用标签包裹工具名与参数 - Runner 将解析后的调用映射到已注册工具并回灌结果 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_tool_prompt/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/llmagent_with_user_history/README.md b/examples/llmagent_with_user_history/README.md index b4620686c..daf294019 100644 --- a/examples/llmagent_with_user_history/README.md +++ b/examples/llmagent_with_user_history/README.md @@ -26,23 +26,22 @@ root_agent (LlmAgent) - 每轮将 `history_content` 与用户当前 `query` 一并作为输入交给 `Runner` - 用于验证“外部检索到的用户历史”与“当前 session 消息列表”的区分 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/llmagent_with_user_history/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/mcp_tools/README.md b/examples/mcp_tools/README.md index e98a29906..292f315e0 100644 --- a/examples/mcp_tools/README.md +++ b/examples/mcp_tools/README.md @@ -47,23 +47,22 @@ mcp_assistant (LlmAgent) - `run_agent.py` 中逐轮打印 `function_call` 和 `function_response` - 便于确认 MCP 请求确实被触发且结果被正确消费 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/mcp_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/mem0_tools/README.md b/examples/mem0_tools/README.md index 8eef052f2..bd02cd086 100644 --- a/examples/mem0_tools/README.md +++ b/examples/mem0_tools/README.md @@ -58,7 +58,7 @@ personal_assistant (LlmAgent) ### 环境要求 -- Python 3.12 +- Python3.10+，推荐 Python3.12 - `mem0ai` - 自托管模式额外需要：`sentence-transformers`、`qdrant-client` @@ -67,17 +67,16 @@ personal_assistant (LlmAgent) ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[mem0]" source .venv/bin/activate -pip3 install -e .[mem0] -pip3 install mem0ai - # Self-hosted mode only pip3 install sentence-transformers qdrant-client ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/mem0_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/memory_service_with_in_memory/README.md b/examples/memory_service_with_in_memory/README.md index eb22ecf6f..065f4cf24 100644 --- a/examples/memory_service_with_in_memory/README.md +++ b/examples/memory_service_with_in_memory/README.md @@ -26,23 +26,22 @@ root_agent (LlmAgent) - `Runner` 绑定内存记忆服务，脚本分三段运行模拟进程级多次启动或会话演进 - Agent 通过工具查询记忆并在回答中引用检索结果 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/memory_service_with_in_memory/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/memory_service_with_mem0/README.md b/examples/memory_service_with_mem0/README.md index 30424d7de..3b924df08 100644 --- a/examples/memory_service_with_mem0/README.md +++ b/examples/memory_service_with_mem0/README.md @@ -32,15 +32,27 @@ memory_assistant (LlmAgent) - TTL 配置：后台周期清理过期记忆，控制成本和数据规模 - 搜索路径：`load_memory` 基于用户维度聚合检索，支持跨 session 召回 -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.10+，推荐 Python3.12 - 需要可用的 LLM 配置（`TRPC_AGENT_*`） - 自托管模式需要 Qdrant 与本地 embedding 相关依赖 -### 运行命令 +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh "[mem0]" +source .venv/bin/activate + +# Self-hosted mode only +pip3 install sentence-transformers qdrant-client +``` + +## 运行步骤 + +### 配置环境变量 ```bash cd examples/memory_service_with_mem0 diff --git a/examples/memory_service_with_mempalace/README.md b/examples/memory_service_with_mempalace/README.md index f64664c78..20f679880 100644 --- a/examples/memory_service_with_mempalace/README.md +++ b/examples/memory_service_with_mempalace/README.md @@ -13,25 +13,34 @@ MemPalace 是一个本地优先的记忆系统，底层使用 ChromaDB 存储 dr - 支持 TTL 后台定时清理过期 drawer。 - 示例输出中会截断过长工具结果，避免 memory JSON 刷屏。 -## 安装依赖 +## 环境要求 -使用前需要安装本项目依赖和 MemPalace 可选依赖。 +- Python3.10+，推荐 Python3.12 -在项目根目录执行： +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[mempalace]" source .venv/bin/activate -pip install -e ".[mempalace]" ``` -如果你使用虚拟环境，请确保运行示例和执行 `mempalace search` 时使用的是同一个环境。 +## 运行步骤 + +### 配置环境变量 -## 运行示例 +在 [examples/memory_service_with_mempalace/.env](./.env) 中设置（也可通过 export）： + +```bash +TRPC_AGENT_API_KEY=... +TRPC_AGENT_BASE_URL=... +TRPC_AGENT_MODEL_NAME=... +``` + +如果你使用虚拟环境，请确保运行示例和执行 `mempalace search` 时使用的是同一个环境。 -在项目根目录执行： +### 运行命令 ```bash cd examples/memory_service_with_mempalace diff --git a/examples/memory_service_with_redis/README.md b/examples/memory_service_with_redis/README.md index 5bfd051fd..246a7a716 100644 --- a/examples/memory_service_with_redis/README.md +++ b/examples/memory_service_with_redis/README.md @@ -32,13 +32,31 @@ weather_agent (LlmAgent) - `search_memory()`：扫描用户维度的记忆键并聚合过滤匹配事件 - `load_memory` 工具：在对话中触发检索，验证跨会话记忆是否可用 -## 环境与运行 - -### 环境要求 +## 环境要求 -- Python 3.12 +- Python3.10+，推荐 Python3.12 - Redis 服务可用（本地 / Docker / 远程） +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate + +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/memory_service_with_redis/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + ### 运行命令 ```bash @@ -81,9 +99,8 @@ python3 run_agent.py ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` --- diff --git a/examples/memory_service_with_sql/README.md b/examples/memory_service_with_sql/README.md index 3c494f2df..a492ef9b8 100644 --- a/examples/memory_service_with_sql/README.md +++ b/examples/memory_service_with_sql/README.md @@ -26,24 +26,22 @@ root_agent (LlmAgent) - 初始化 SQL 记忆服务并注入 `Runner`，与内存版示例结构平行 - Agent 通过 `load_memory` 查询后根据返回 JSON 组织回复 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 -- 按 `.env` 配置可用的 SQL 连接（与示例一致） - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/memory_service_with_sql/.env](./.env) 中配置模型与数据库相关变量（以该文件为准）。 diff --git a/examples/mempalace_mcp/README.md b/examples/mempalace_mcp/README.md index 566541858..e3db5d487 100644 --- a/examples/mempalace_mcp/README.md +++ b/examples/mempalace_mcp/README.md @@ -34,19 +34,26 @@ LlmAgent --stdio--> mempalace mcp (子进程, MCP server) --- -## 准备工作 +## 环境要求 -### 1. 安装依赖 +- Python3.10+，推荐 Python3.12 + +## 构建步骤 在仓库根目录： ```bash -pip install -e ".[mempalace]" +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh "[mempalace]" +source .venv/bin/activate ``` `mempalace` 包会带上 `mempalace` CLI 命令到当前 Python 环境的 PATH。 -### 2. 初始化 palace（首次使用） +## 运行步骤 + +### 初始化 palace（首次使用） ```bash mempalace init @@ -59,9 +66,9 @@ export MEMPALACE_PALACE_PATH=/absolute/path/to/palace mempalace --palace "$MEMPALACE_PALACE_PATH" init ``` -### 3. 配置模型 key +### 配置环境变量 -复制并填写 `.env`： +在 [examples/mempalace_mcp/.env](./.env) 中设置（也可通过 export）： ```env TRPC_AGENT_API_KEY=your-api-key @@ -72,14 +79,14 @@ TRPC_AGENT_MODEL_NAME=your-model-name --- -## 启动 MemPalace MCP Server +### 启动 MemPalace MCP Server > ⚠️ **重要**：`mempalace mcp`（带空格）**不是** MCP server，它只是打印设置帮助。 > 真正的 server 入口是 `mempalace-mcp`（带连字符）或 `python -m mempalace.mcp_server`。 MemPalace MCP server 有 **3 种启动方式**，本示例使用第 1 种，**完全无需手动操作**： -### 方式 1：自动 stdio 子进程（本示例采用，推荐） +#### 方式 1：自动 stdio 子进程（本示例采用，推荐） `MempalaceMCPToolset` 在 `LlmAgent` 启动时**自动**把 server 作为子进程拉起，通过 stdin/stdout 与之通信；`Runner` 关闭时子进程也跟着退出。**你什么都不用做，跑 `python3 run_agent.py` 即可。** @@ -102,7 +109,7 @@ McpStdioServerParameters( McpStdioServerParameters(command="mempalace-mcp", args=[...], env=env) ``` -### 方式 2：手动启动 stdio server（用于调试） +#### 方式 2：手动启动 stdio server（用于调试） 要确认 MemPalace MCP server 本身可用，先在终端单独跑一下： @@ -130,7 +137,7 @@ stdio 协议要求 stdout 纯净，否则 MCP 客户端会无法解析。 | `mempalace-mcp`（带连字符） | ✅ 真正启动 stdio server | | `python -m mempalace.mcp_server` | ✅ 真正启动 stdio server（最稳） | -### 方式 3：作为常驻 HTTP server（多 agent 共享同一 palace） +#### 方式 3：作为常驻 HTTP server（多 agent 共享同一 palace） 如果你希望多个 agent 共享同一个 MemPalace，可以让 MCP server 跑成 HTTP 服务（具体 CLI 选项请参考 MemPalace 官方文档当前版本：[mempalace mcp](https://mempalaceofficial.com/reference/cli)）。然后把 @@ -152,7 +159,7 @@ self._connection_params = StreamableHTTPConnectionParams( --- -## 运行示例 +### 运行命令 ```bash cd examples/mempalace_mcp diff --git a/examples/mempalace_tools/README.md b/examples/mempalace_tools/README.md index 6b04f9d10..85824ba0e 100644 --- a/examples/mempalace_tools/README.md +++ b/examples/mempalace_tools/README.md @@ -51,23 +51,26 @@ personal_assistant (LlmAgent) | `MempalaceKGTimelineTool` | `mempalace_kg_timeline` | 按时间线读取知识图谱事实，可限定某个实体。 | `entity` | 用户要求“展示 Alice 的知识图谱时间线”。 | | `MempalaceKGInvalidateTool` | `mempalace_kg_invalidate` | 将一条当前事实标记为失效，用于表达事实变化，而不是直接删除历史。 | `subject`、`predicate`、`object`、`ended` | 用户要求“把 Alice likes Italian food 标记为今天结束”。 | -## 安装 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[mempalace]" source .venv/bin/activate - -pip3 install -e . -pip3 install mempalace ``` 如果你的 MemPalace 安装需要额外向量依赖，请按 MemPalace 官方说明补装对应 embedding 或 Chroma 依赖。 -## 环境变量 +## 运行步骤 -在 `examples/mempalace_tools/.env` 中配置，或通过 `export` 设置： +### 配置环境变量 + +在 [examples/mempalace_tools/.env](./.env) 中配置，或通过 `export` 设置： ```bash TRPC_AGENT_API_KEY=your-api-key @@ -86,13 +89,15 @@ MEMPALACE_ROOM=user_profile - `wing`：建议映射到应用或用户级作用域，例如 `app/user`、`personal_assistant_alice`。 - `room`：建议映射到记忆主题，例如 `user_profile`、`preferences`、`work_notes`。 -## 运行 +### 运行命令 ```bash cd examples/mempalace_tools python3 run_agent.py ``` +## 运行结果 + 示例分三个阶段执行。每条消息都会使用新的 `session_id`，用于验证不同 session 之间仍能通过 MemPalace 读到之前写入的数据。 第一阶段写入数据并立即用新 session 查询： diff --git a/examples/multi_agent_chain/README.md b/examples/multi_agent_chain/README.md index e8fcbfed9..0ba6d3935 100644 --- a/examples/multi_agent_chain/README.md +++ b/examples/multi_agent_chain/README.md @@ -27,23 +27,22 @@ chain_root (ChainAgent) - `ChainAgent(sub_agents=[extractor_agent, translator_agent], ...)` - 上游输出键写入 runner state，下游指令中引用该键 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_chain/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/multi_agent_compose/README.md b/examples/multi_agent_compose/README.md index c6fbd1e30..823e6b687 100644 --- a/examples/multi_agent_compose/README.md +++ b/examples/multi_agent_compose/README.md @@ -28,23 +28,22 @@ compose_root（Compose 编排入口） - Compose 将多个子 Agent 的结果在编排层合并或续写 - `run_agent.py` 打印各阶段标题与正文片段 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_compose/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/multi_agent_cycle/README.md b/examples/multi_agent_cycle/README.md index 6b4030509..9dfdcdf99 100644 --- a/examples/multi_agent_cycle/README.md +++ b/examples/multi_agent_cycle/README.md @@ -27,23 +27,22 @@ cycle_root (Cycle / loop orchestration) - 评估 Agent 在高分时调用退出工具，循环终止 - 写手根据评估反馈（若有）在下一轮改写 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_cycle/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/multi_agent_parallel/README.md b/examples/multi_agent_parallel/README.md index d0cf85aa8..328653536 100644 --- a/examples/multi_agent_parallel/README.md +++ b/examples/multi_agent_parallel/README.md @@ -27,23 +27,22 @@ parallel_root（并行编排） - 编排层等待各子 Agent 完成再拼接输出 - 适合 I/O 或模型调用可并行的独立评审维度 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_parallel/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/multi_agent_start_from_last/README.md b/examples/multi_agent_start_from_last/README.md index 4193efebd..01dc5aaa6 100644 --- a/examples/multi_agent_start_from_last/README.md +++ b/examples/multi_agent_start_from_last/README.md @@ -27,23 +27,22 @@ coordinator（协调 Agent） - Runner/Team 配置 `start_from_last_agent=True` - 用户 Turn 2/3 的意图延续由上次活跃子 Agent 直接处理 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_start_from_last/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/multi_agent_subagent/README.md b/examples/multi_agent_subagent/README.md index 1f80372d2..00bac5a3e 100644 --- a/examples/multi_agent_subagent/README.md +++ b/examples/multi_agent_subagent/README.md @@ -27,23 +27,22 @@ customer_service_coordinator - 协调者先 `generate_consult_id`，再 `transfer_to_agent` - 子 Agent 独立工具集，体现多角色客服分流 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/multi_agent_subagent/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/plan_mode/README.md b/examples/plan_mode/README.md index ea0bc33cb..7365d48fc 100644 --- a/examples/plan_mode/README.md +++ b/examples/plan_mode/README.md @@ -39,24 +39,32 @@ orchestrator (LlmAgent + setup_plan) - 计划文档持久化在**主 agent 的 session** 中（`state["plan"]`）。 - 被 spawn 出来的子 agent 只返回文本，不直接改动主 agent 的状态。 -## 前置条件 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 ```bash # 1. 安装 SDK（含 AG-UI 依赖） git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[ag-ui]" source .venv/bin/activate -pip3 install -e . - -# 2. 配置模型访问 -# 复制并填写 examples/plan_mode/.env： -TRPC_AGENT_API_KEY=<你的 key> -TRPC_AGENT_BASE_URL=<可选，自定义 endpoint> -TRPC_AGENT_MODEL_NAME=<可选，默认 gpt-4.1-mini> +pip3 install fastapi ``` -## 运行 +## 运行步骤 + +### 配置环境变量 + +在 [examples/plan_mode/.env](./.env) 中设置（也可通过 export）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/plan_mode diff --git a/examples/plan_mode_with_goal_and_task/README.md b/examples/plan_mode_with_goal_and_task/README.md index 78a3794ed..87a9a6d20 100644 --- a/examples/plan_mode_with_goal_and_task/README.md +++ b/examples/plan_mode_with_goal_and_task/README.md @@ -48,20 +48,29 @@ orchestrator (LlmAgent) > Plan gate 激活期间，`task_create` / `task_update` / `create_goal` / `update_goal` 会被 `PLAN_MODE_GATE` 拦截（见 `DEFAULT_WRITE_TOOL_NAMES`）。 -## 前置条件 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 ```bash +git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv && source .venv/bin/activate -pip3 install -e '.[ag-ui]' - -# 配置 examples/plan_mode_with_goal_and_task/.env -TRPC_AGENT_API_KEY=<你的 key> -TRPC_AGENT_BASE_URL=<可选> -TRPC_AGENT_MODEL_NAME=<可选，默认 gpt-4.1-mini> +./build.sh "[ag-ui]" +source .venv/bin/activate ``` +## 运行步骤 + +### 配置环境变量 + +在 [examples/plan_mode_with_goal_and_task/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` -## 运行 +### 运行命令 ```bash cd examples/plan_mode_with_goal_and_task diff --git a/examples/quickstart/README.md b/examples/quickstart/README.md index b0d785528..653d1ae68 100644 --- a/examples/quickstart/README.md +++ b/examples/quickstart/README.md @@ -26,23 +26,22 @@ root_agent (LlmAgent) - 每轮使用新 `session_id` 或按脚本逻辑创建会话 - 展示环境变量加载后与云端模型的一次完整 tool loop -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/quickstart/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/session_service_with_in_memory/README.md b/examples/session_service_with_in_memory/README.md index 650e6bb56..1c59d7d04 100644 --- a/examples/session_service_with_in_memory/README.md +++ b/examples/session_service_with_in_memory/README.md @@ -26,23 +26,22 @@ root_agent (LlmAgent) - 每段 run 使用脚本定义的会话策略，观察会话服务生命周期 - 与 Memory Service 示例不同：此处强调 session 存储而非独立 memory 工具检索 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/session_service_with_in_memory/.env](./.env) 中配置（或通过 `export` 设置）： @@ -59,7 +58,6 @@ python3 run_agent.py ## 运行结果（实测） - ```text First run 🤖 Assistant: No, I don't have the ability to remember ... between conversations... diff --git a/examples/session_service_with_redis/README.md b/examples/session_service_with_redis/README.md index 3704fdc77..84d4abc6f 100644 --- a/examples/session_service_with_redis/README.md +++ b/examples/session_service_with_redis/README.md @@ -32,13 +32,30 @@ weather_agent (LlmAgent) - `RedisSessionService.save_session()`：持久化事件和状态并设置过期时间 - `run_agent.py`：通过三次运行（间隔控制）验证 TTL 与状态恢复行为 -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.10+，推荐 Python3.12 - 可用 Redis 服务 +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/session_service_with_redis/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + ### 运行命令 ```bash diff --git a/examples/session_service_with_sql/README.md b/examples/session_service_with_sql/README.md index 1441b4f02..9892db085 100644 --- a/examples/session_service_with_sql/README.md +++ b/examples/session_service_with_sql/README.md @@ -26,27 +26,31 @@ root_agent (LlmAgent) - 初始化 SQL Session 后端并注入 `Runner` - 与内存版脚本结构对称，便于对比持久化语义 -## 环境与运行 +## 环境要求 -### 环境要求 - -- Python 3.12 +- Python3.12 - 按 `.env` 提供可用的 SQL 配置 -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 + 在 [examples/session_service_with_sql/.env](./.env) 中配置模型与数据库相关变量（以该文件为准）。 +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + ### 运行命令 ```bash diff --git a/examples/session_state/README.md b/examples/session_state/README.md index d000dadd2..2231bf89e 100644 --- a/examples/session_state/README.md +++ b/examples/session_state/README.md @@ -30,23 +30,22 @@ state_demo_agent (LlmAgent + set_state_at_different_levels) - `run_agent.py` 按块运行四个示例，每块打印用户输入、工具调用与当前各级 state 快照 - 展示 `output_key` 与协作子 Agent 输出合并进 state 的模式 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/session_state/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/session_summarizer/README.md b/examples/session_summarizer/README.md index b6f1c88fa..aa158544d 100644 --- a/examples/session_summarizer/README.md +++ b/examples/session_summarizer/README.md @@ -29,23 +29,22 @@ python_tutor (LlmAgent) - `run_agent_with_summarizer_manager()`：执行多轮会话并在关键回合打印会话压缩状态 - 手动摘要阶段：在末尾显式触发一次摘要，验证高压缩率下的最终状态 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/session_summarizer/.env](./.env) 中配置（或通过 `export` 设置）： diff --git a/examples/skills/README.md b/examples/skills/README.md index 1cd5d8f4f..f20640dcc 100644 --- a/examples/skills/README.md +++ b/examples/skills/README.md @@ -19,12 +19,32 @@ - `agent/tools.py`：`create_local_workspace_runtime` + `create_default_skill_repository` 构造 `SkillToolSet` - `agent/agent.py`：将 `skill_tool_set` 与 `skill_repository` 绑定到 `LlmAgent` -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录执行 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（可用 `.env`） +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/skills/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` - 可选：`SKILLS_ROOT` 指向技能根目录 +### 运行命令 + ```bash cd examples/skills python3 run_agent.py diff --git a/examples/skills_code_review_agent/.env.example b/examples/skills_code_review_agent/.env similarity index 100% rename from examples/skills_code_review_agent/.env.example rename to examples/skills_code_review_agent/.env diff --git a/examples/skills_code_review_agent/README.md b/examples/skills_code_review_agent/README.md index 318916499..78c82f642 100644 --- a/examples/skills_code_review_agent/README.md +++ b/examples/skills_code_review_agent/README.md @@ -50,9 +50,23 @@ skills_code_review_agent/ └── examples/review_report.* # 示例报告 ``` -## 运行要求 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 前置说明 -- Python 3.10+ - 已按仓库根目录说明安装 `trpc-agent-python` 及其现有依赖 - fake/dry-run 不需要 Docker 或模型 API Key - 真实模式需要 Docker daemon，以及模型环境变量 @@ -62,6 +76,10 @@ skills_code_review_agent/ 生产环境建议设置 `TRPC_AGENT_ALLOWED_MODEL_HOSTS`，限制可接收 API Key 和审查证据的模型服务域名。 +### 配置环境变量 + +在 [examples/skills_code_review_agent/.env](./.env) 中配置 + 本示例不额外依赖 `.env` 解析库。入口只读取示例目录下权限为 `0600`、 键名前缀为 `TRPC_AGENT_` 或 `CODE_REVIEW_` 的普通文件；同名进程变量优先： diff --git a/examples/skills_hub/README.md b/examples/skills_hub/README.md index c0ea5526f..f14739a53 100644 --- a/examples/skills_hub/README.md +++ b/examples/skills_hub/README.md @@ -37,12 +37,36 @@ Skill Hub（`trpc_agent_sdk.skills.hub`）把"从各种来源发现并获取 ski - `agent/agent.py`：`create_agent(skills_dir)` 把返回的 `skill_repository` / `skill_tool_set` 绑定到 `LlmAgent` - `run_agent.py`：清空 `data/` 目录（保证每次都重新走一遍 Skill Hub 拉取流程），创建 agent，跑一轮 `skill_load` + 总结的对话，并打印实际下载到的文件列表 -## 环境与运行 +## 环境要求 -- Python 3.10+；仓库根目录执行 `pip install -e .` +- Python3.10+，推荐 Python3.12 + +- Python3.10+ - 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（可用 `.env`） - 可选：`GITHUB_TOKEN`，用于提高 GitHub API 限额（本示例只读取公开仓库，不设置也能跑） +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/skills_hub/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` +- `GITHUB_TOKEN` 用于提高 GitHub API 限额（本示例只读取公开仓库，不设置也能跑） + +### 运行命令 + ```bash cd examples/skills_hub python3 run_agent.py diff --git a/examples/skills_with_container/README.md b/examples/skills_with_container/README.md index 2b830dd4b..2f7220161 100644 --- a/examples/skills_with_container/README.md +++ b/examples/skills_with_container/README.md @@ -19,12 +19,32 @@ - `run_agent.py`：组装含 `inputs` 数组的 JSON 提示词，驱动单次 `skill_run` 演示 - `run_agent.py` 末尾清理 `/tmp/skillrun-inputs` 等临时文件 -## 环境与运行 +## 环境要求 -- Python 3.12；已安装 Docker；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/skills_with_container/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` - 可选：`SKILLS_ROOT`、`SKILLS_INPUTS_HOST`（默认 `/tmp/skillrun-inputs`） +### 运行命令 + ```bash cd examples/skills_with_container python3 run_agent.py diff --git a/examples/skills_with_cube/README.md b/examples/skills_with_cube/README.md index 6870353f5..e93202ec8 100644 --- a/examples/skills_with_cube/README.md +++ b/examples/skills_with_cube/README.md @@ -20,12 +20,33 @@ - `agent/agent.py`：异步创建 agent，并把 workspace runtime 返回给 runner 做最终销毁 - `run_agent.py`：组装含 `inputs` 数组的 JSON 提示词，驱动单次 `skill_run` 演示，并在 finally 中销毁沙箱 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录安装 Cube extra：`pip install -e '.[cube]'` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` -- 配置 Cube 环境变量：`CUBE_TEMPLATE_ID`、`E2B_API_URL`、`E2B_API_KEY` -- 可选：`SKILLS_ROOT`、`CUBE_EXECUTE_TIMEOUT`（默认 `30`）、`CUBE_IDLE_TIMEOUT`（默认 `600`） +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh "[cube]" +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/skills_with_cube/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` +- `CUBE_TEMPLATE_ID=your-cube-template-id` +- `E2B_API_URL=your-e2b-api-url` +- `E2B_API_KEY=your-e2b-api-key` + +### 运行命令 ```bash cd examples/skills_with_cube diff --git a/examples/skills_with_dynamic_tools/README.md b/examples/skills_with_dynamic_tools/README.md index c4c1e2783..e1083feed 100644 --- a/examples/skills_with_dynamic_tools/README.md +++ b/examples/skills_with_dynamic_tools/README.md @@ -19,12 +19,32 @@ - `agent/tools/_dynamic.py`：`DynamicSkillToolSet` 配置 `available_tools`（含 `FunctionTool(ask_name_information)` 等） - `run_agent.py`：单条长提示触发 `skill_list` → `skill_load` → `skill_select_tools` → 多次工具调用 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/skills_with_container/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` - 技能目录默认在示例内 `skills/`，可通过环境变量 `SKILLS_ROOT` 覆盖 +### 运行命令 + ```bash cd examples/skills_with_dynamic_tools python3 run_agent.py diff --git a/examples/spawn_subagent/README.md b/examples/spawn_subagent/README.md index 3894bb695..f99358b19 100644 --- a/examples/spawn_subagent/README.md +++ b/examples/spawn_subagent/README.md @@ -10,10 +10,35 @@ 无论哪种方式，子 Agent 的 instruction、工具集、模型都被锁定——LLM 只能选择 `subagent_type` 和写 `prompt`，无法在调用时改写子 Agent 的角色。 -## 运行 +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/spawn_subagent/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash # 零配置（仅 default 子 Agent） +cd examples/spawn_subagent + python run_agent.py # 代码定义子 Agent（security-auditor + Explore + Plan） diff --git a/examples/streaming_tools/README.md b/examples/streaming_tools/README.md index 1916fe50b..57ed759dc 100644 --- a/examples/streaming_tools/README.md +++ b/examples/streaming_tools/README.md @@ -19,10 +19,30 @@ - `agent/agent.py`：注册 `StreamingFunctionTool` 与 `FunctionTool` - `agent/tools.py`：实现 `write_file`、`get_file_info` 的具体逻辑 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（可用 `.env`） +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/streaming_tools/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/streaming_tools diff --git a/examples/task_tools/README.md b/examples/task_tools/README.md index a578a056b..f0088e53b 100644 --- a/examples/task_tools/README.md +++ b/examples/task_tools/README.md @@ -76,23 +76,22 @@ task_planner (LlmAgent) - **Prompt 引导（鼓励不强制）**：`DEFAULT_TASK_PROMPT` 在挂载工具时经 `process_request` 自动追加到 system instruction。 - 原则：要强制就加 validator，不要把约束塞进 prompt，两层保持可区分。 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/task_tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/team/README.md b/examples/team/README.md index 5ce82da01..dc98fa810 100644 --- a/examples/team/README.md +++ b/examples/team/README.md @@ -19,10 +19,30 @@ - `run_agent.py`：创建单次会话，循环发送两条 `demo_queries` 并打印事件 - `agent/tools.py`：模拟 `search_web`、`check_grammar`、`get_current_date` -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team diff --git a/examples/team_as_sub_agent/README.md b/examples/team_as_sub_agent/README.md index 2e86bfb9f..a3b7e4c37 100644 --- a/examples/team_as_sub_agent/README.md +++ b/examples/team_as_sub_agent/README.md @@ -23,7 +23,7 @@ ## 环境与运行 -- Python 3.12；仓库根目录 `pip install -e .` +- Python3.12；仓库根目录 `pip install -e .` - 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` ```bash diff --git a/examples/team_human_in_the_loop/README.md b/examples/team_human_in_the_loop/README.md index c15d35d30..5f3c0b7c1 100644 --- a/examples/team_human_in_the_loop/README.md +++ b/examples/team_human_in_the_loop/README.md @@ -19,10 +19,30 @@ - `agent/tools.py`：`request_approval`、`search_info` 的实现与 HITL 演示配合 - `run_agent.py`：捕获 pending、打印 `HITL TRIGGERED!` 后注入批准结果并继续 `run_async` -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_human_in_the_loop/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_human_in_the_loop diff --git a/examples/team_member_agent_claude/README.md b/examples/team_member_agent_claude/README.md index 9e7dcee4c..33009dd87 100644 --- a/examples/team_member_agent_claude/README.md +++ b/examples/team_member_agent_claude/README.md @@ -41,25 +41,25 @@ assistant_team (Leader, LlmAgent) - 运行日志包含 proxy 进程启动、event loop thread 生命周期和最终清理 - 结束时出现 `Cleaned up Claude environment`，说明清理流程完整 -## 环境与运行 -### 环境要求 +## 环境要求 -- Python 3.12 +- Python3.10+，推荐 Python3.12 -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[agent-claude]" source .venv/bin/activate -pip3 install -e .[agent-claude] ``` -### 环境变量要求 +## 运行步骤 -在 [examples/team_member_agent_claude/.env](./.env) 中配置（或通过 `export`）： +### 配置环境变量 + +在 [examples/team_human_in_the_loop/.env](./.env) 中配置（或通过 `export`）： - `TRPC_AGENT_API_KEY` - `TRPC_AGENT_BASE_URL` diff --git a/examples/team_member_agent_langgraph/README.md b/examples/team_member_agent_langgraph/README.md index 94348dfab..c644845ae 100644 --- a/examples/team_member_agent_langgraph/README.md +++ b/examples/team_member_agent_langgraph/README.md @@ -19,10 +19,30 @@ - `agent/tools.py`：`calculate` 供 LangGraph 工具节点调用 - `run_agent.py`：两轮算术问句，展示委派与 `calculate` 工具响应 -## 环境与运行 +## 环境要求 -- Python 3.12；安装本仓库与 LangGraph / LangChain 相关依赖；`pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（示例使用 `deepseek:` 前缀初始化 chat model） +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh "[graph, deepseek-langchain]" +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_member_agent_langgraph/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_member_agent_langgraph diff --git a/examples/team_member_agent_team/README.md b/examples/team_member_agent_team/README.md index 5c7e6de21..b50fbf3f0 100644 --- a/examples/team_member_agent_team/README.md +++ b/examples/team_member_agent_team/README.md @@ -21,10 +21,28 @@ - `agent/tools.py`：`design_api`、`design_ui`、`format_docs` 等 - `run_agent.py`：多轮产品需求对话，打印跨层委派与工具调用 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh "[graph]" +source .venv/bin/activate +``` + +### 配置环境变量 + +在 [examples/team_member_agent_team/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_member_agent_team diff --git a/examples/team_member_message_filter/README.md b/examples/team_member_message_filter/README.md index 1c1ebfa32..cd637020f 100644 --- a/examples/team_member_message_filter/README.md +++ b/examples/team_member_message_filter/README.md @@ -19,10 +19,30 @@ - `run_agent.py`：简化打印 tool call/response 与流式文本 - `agent/tools.py`：销售拉取与统计、趋势分析等模拟工具 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_member_message_filter/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_member_message_filter diff --git a/examples/team_parallel_execution/README.md b/examples/team_parallel_execution/README.md index e94795e17..11a63a1ff 100644 --- a/examples/team_parallel_execution/README.md +++ b/examples/team_parallel_execution/README.md @@ -19,10 +19,31 @@ - `run_agent.py`：单用户长查询，打印带 `[秒]` 前缀的时间线 - `agent/tools.py`：`analyze_market_trends`、`analyze_competitor`、`analyze_risks` -## 环境与运行 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +## 环境要求 + +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_parallel_execution/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_parallel_execution diff --git a/examples/team_with_cancel/README.md b/examples/team_with_cancel/README.md index e3fc03666..f31e859d4 100644 --- a/examples/team_with_cancel/README.md +++ b/examples/team_with_cancel/README.md @@ -19,10 +19,30 @@ - `run_agent.py`：多场景顺序执行——先触发取消再追问「what happened?」等 - `agent/tools.py`：`search_web`、`check_grammar` 等（含延迟） -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_with_cancel/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_with_cancel diff --git a/examples/team_with_skill/README.md b/examples/team_with_skill/README.md index 7273c7395..0aae9b620 100644 --- a/examples/team_with_skill/README.md +++ b/examples/team_with_skill/README.md @@ -19,11 +19,30 @@ - `agent/tools.py`：封装 `create_skill_tool_set` 及成员侧工具 - `run_agent.py`：用户强制流程——先跑技能命令再委派成员 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME` -- 技能位于示例目录 `skills/`（可通过环境变量指定根路径） +- Python3.10+，推荐 Python3.12 + +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/team_with_skill/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/team_with_skill diff --git a/examples/todo_tool/README.md b/examples/todo_tool/README.md index 1e9b282c6..e7bd1b1bf 100644 --- a/examples/todo_tool/README.md +++ b/examples/todo_tool/README.md @@ -76,23 +76,22 @@ def _all_done_nudge_hook(old, new): - **Prompt 引导（鼓励不强制）**：`DEFAULT_TODO_PROMPT` 在挂载工具时经 `process_request` 自动追加到 system instruction。 - 原则：要强制就加 validator，不要把约束塞进 prompt，两层保持可区分。 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/todo_tool/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/todo_tool_with_human_in_the_loop/README.md b/examples/todo_tool_with_human_in_the_loop/README.md index 42b047288..5e7be3f2b 100644 --- a/examples/todo_tool_with_human_in_the_loop/README.md +++ b/examples/todo_tool_with_human_in_the_loop/README.md @@ -108,23 +108,22 @@ read_tool = ReadTool(cwd=cwd) 工具名必须为 `Bash` / `Write` / `Read`（区分大小写），由框架 schema 暴露给模型。 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量 +## 运行步骤 + +### 配置环境变量 在 [examples/todo_tool_with_human_in_the_loop/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/tools/README.md b/examples/tools/README.md index 19d17597f..8e2316b16 100644 --- a/examples/tools/README.md +++ b/examples/tools/README.md @@ -51,23 +51,23 @@ run_agent.py - `WeatherToolSet.get_tools(...)` 读取 `invocation_context.session.state["user_type"]` - BASIC 用户仅能用当前天气工具，VIP 用户可额外使用预报工具 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh "[langchain_tool]" source .venv/bin/activate -pip3 install -e .[langchain_tool] ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 + 在 [examples/tools/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/toolsets/README.md b/examples/toolsets/README.md index 5d0063ad6..31d10c7eb 100644 --- a/examples/toolsets/README.md +++ b/examples/toolsets/README.md @@ -19,11 +19,30 @@ - `agent/agent.py`：`weather_toolset.initialize()` 后作为唯一 `tools` 传入 - `run_agent.py`：`test_scenarios` 循环 BASIC 与 VIP 两组问答 -## 环境与运行 +## 环境要求 -- Python 3.12；仓库根目录 `pip install -e .` -- 配置 `TRPC_AGENT_API_KEY`、`TRPC_AGENT_BASE_URL`、`TRPC_AGENT_MODEL_NAME`（可用 `.env`） +- Python3.10+，推荐 Python3.12 +## 构建步骤 + +```bash +git clone https://github.com/trpc-group/trpc-agent-python.git +cd trpc-agent-python +./build.sh +source .venv/bin/activate +``` + +## 运行步骤 + +### 配置环境变量 + +在 [examples/toolsets/.env](./.env) 中配置（或通过 `export`）： + +- `TRPC_AGENT_API_KEY` +- `TRPC_AGENT_BASE_URL` +- `TRPC_AGENT_MODEL_NAME` + +### 运行命令 ```bash cd examples/toolsets python3 run_agent.py diff --git a/examples/transfer_agent/README.md b/examples/transfer_agent/README.md index ec63d4d84..fe7f5c7cd 100644 --- a/examples/transfer_agent/README.md +++ b/examples/transfer_agent/README.md @@ -44,23 +44,22 @@ root_agent (TransferAgent wrapper) - 运行日志按节点分段打印，便于确认每一步是否执行 - 可直接判断“外部查询 -> 转交 -> 二次输出”的完整性 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/transfer_agent/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/webfetch_tool/README.md b/examples/webfetch_tool/README.md index c0bedba94..0839f3721 100644 --- a/examples/webfetch_tool/README.md +++ b/examples/webfetch_tool/README.md @@ -113,23 +113,22 @@ ssrf_fetch_agent (LlmAgent) # SSRF 防护（loopback / 元 - `http://10.0.0.1/` — RFC 1918 内网网段，覆盖"Agent 跑在 VPC / k8s 集群里被用来扫内网" - 仅当调用方已用外部白名单限定目标、并确信输入可信（如内网集群）时才考虑关闭该开关；关闭后示例 5 的三条 payload 会真的发起连接，生产环境请谨慎评估 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/webfetch_tool/.env](./.env) 中配置（或通过 `export`）： diff --git a/examples/websearch_tool/README.md b/examples/websearch_tool/README.md index e58231679..98bc90e0d 100644 --- a/examples/websearch_tool/README.md +++ b/examples/websearch_tool/README.md @@ -124,23 +124,22 @@ google_raw_agent (LlmAgent) # dedup_urls=False + 6 个月时效性 - `google_raw_agent` 使用 `google_extra_params={"dateRestrict": "m6"}` —— 只保留过去 6 个月内被 Google 索引的结果，适合"最新/what's new"类查询 - 其他常见透传包括 Google CSE 的 `gl`（地理偏向）、`cr`（国家限制）、`filter`、`sort` 等 -## 环境与运行 +## 环境要求 -### 环境要求 +- Python3.10+，推荐 Python3.12 -- Python 3.12 - -### 安装步骤 +## 构建步骤 ```bash git clone https://github.com/trpc-group/trpc-agent-python.git cd trpc-agent-python -python3 -m venv .venv +./build.sh source .venv/bin/activate -pip3 install -e . ``` -### 环境变量要求 +## 运行步骤 + +### 配置环境变量 在 [examples/websearch_tool/.env](./.env) 中配置（或通过 `export`）： diff --git a/pipeline_test/_install_deps.sh b/pipeline_test/_install_deps.sh new file mode 100644 index 000000000..aec8f8982 --- /dev/null +++ b/pipeline_test/_install_deps.sh @@ -0,0 +1,83 @@ +#!/usr/bin/env bash +# Shared uv-based installer for pipeline_test scripts. +# Default: cache enabled for faster repeated CI/local runs. +# Disable with: USE_CACHE=0 + +pipeline_ensure_uv() { + local python_bin="${PYTHON_BIN:-python3}" + + if command -v uv >/dev/null 2>&1; then + return 0 + fi + + if "${python_bin}" -m uv --version >/dev/null 2>&1; then + return 0 + fi + + echo "uv not found; installing uv..." + "${python_bin}" -m pip install --upgrade uv +} + +pipeline_uv_cmd() { + local python_bin="${PYTHON_BIN:-python3}" + + if command -v uv >/dev/null 2>&1; then + uv "$@" + else + "${python_bin}" -m uv "$@" + fi +} + +pipeline_uv_cache_args() { + # Cache on by default in pipeline_test (opposite of build.sh cold-install default). + if [[ "${USE_CACHE:-1}" == "1" ]]; then + echo "uv package cache enabled (USE_CACHE=1)." >&2 + return 0 + fi + + echo "uv package cache disabled (USE_CACHE=0)." >&2 + printf '%s\n' --no-cache +} + +# Usage: +# pipeline_uv_install_extras "graph,a2a" +# pipeline_uv_install_extras "eval" +pipeline_uv_install_extras() { + local extras="${1:?extras required}" + local python_bin="${PYTHON_BIN:-python3}" + local cache_args=() + local arg + + pipeline_ensure_uv + + while IFS= read -r arg; do + [[ -n "${arg}" ]] && cache_args+=("${arg}") + done < <(pipeline_uv_cache_args) + + echo "Installing editable package with extras: [${extras}]" + pipeline_uv_cmd pip install \ + "${cache_args[@]}" \ + --python "${python_bin}" \ + -e ".[${extras}]" +} + +# Usage: +# pipeline_uv_install_requirements "pipeline_test/requirements.txt" +pipeline_uv_install_requirements() { + local req_file="${1:?requirements file required}" + local python_bin="${PYTHON_BIN:-python3}" + local cache_args=() + local arg + + pipeline_ensure_uv + + while IFS= read -r arg; do + [[ -n "${arg}" ]] && cache_args+=("${arg}") + done < <(pipeline_uv_cache_args) + + echo "Installing requirements from: ${req_file}" + pipeline_uv_cmd pip install \ + "${cache_args[@]}" \ + --python "${python_bin}" \ + -r "${req_file}" +} diff --git a/pipeline_test/run_agent_examples.sh b/pipeline_test/run_agent_examples.sh index cc20c8677..cd4feb6e8 100644 --- a/pipeline_test/run_agent_examples.sh +++ b/pipeline_test/run_agent_examples.sh @@ -4,7 +4,45 @@ export DISABLE_TRPC_AGENT_REPORT=true set -e -pip3 install -r pipeline_test/requirements.txt +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +cd "$REPO_ROOT" + +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if ! PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Error: no project virtual environment found (.venv or venv)." >&2 + echo "Create one first, for example: ./build.sh" >&2 + exit 1 +fi + +echo "Using project virtual environment: ${PROJECT_VENV_DIR}" +# shellcheck source=/dev/null +source "${PROJECT_VENV_DIR}/bin/activate" +# export PYTHON_BIN="${REPO_ROOT}/${PROJECT_VENV_DIR}/bin/python" + +# shellcheck source=pipeline_test/_install_deps.sh +source "${SCRIPT_DIR}/_install_deps.sh" + +# graph/* and team_member_agent_langgraph need [graph] +pipeline_uv_install_extras "graph, deepseek-langchain" +pipeline_uv_install_requirements "pipeline_test/requirements.txt" # Define example categories LLM_AGENT_EXAMPLES=( @@ -125,4 +163,4 @@ else exit 1 ;; esac -fi \ No newline at end of file +fi diff --git a/pipeline_test/run_all_examples.sh b/pipeline_test/run_all_examples.sh index acc98bf60..6396e8ddf 100644 --- a/pipeline_test/run_all_examples.sh +++ b/pipeline_test/run_all_examples.sh @@ -22,6 +22,39 @@ EVALUATION_TESTS=() TOTAL_TASKS=0 CURRENT_TASK=0 +cd "$REPO_ROOT" + +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if ! PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Error: no project virtual environment found (.venv or venv)." >&2 + echo "Create one first, for example: ./build.sh" >&2 + exit 1 +fi + +echo "Using project virtual environment: ${PROJECT_VENV_DIR}" +# shellcheck source=/dev/null +source "${PROJECT_VENV_DIR}/bin/activate" +# export PYTHON_BIN="${REPO_ROOT}/${PROJECT_VENV_DIR}/bin/python" +cd - + + SKIPPED_EXAMPLES=( "examples/claude_agent_with_travel_planner/run_agent.py" "examples/dsl/classifier_mcp/run_agent.py" @@ -62,6 +95,10 @@ Environment: EXTRA_SKIP_EXAMPLES Space-separated run_agent.py paths to skip. EXAMPLE_TIMEOUT_SECONDS Max seconds for each example before marking it failed. + +Notes: + Installs matching optional extras with uv before running (cache on by default). + Disable cache with USE_CACHE=0. With --include-manual, also installs mem0 and cube. EOF } @@ -365,6 +402,33 @@ while (($# > 0)); do done cd "$REPO_ROOT" + +# shellcheck source=pipeline_test/_install_deps.sh +source "${SCRIPT_DIR}/_install_deps.sh" + +# Install optional extras required by the selected mode. +case "$RUN_MODE" in + all) + EXTRAS="graph,a2a,agent-claude,knowledge,knowledge-hf,langchain_tool,mempalace,eval" + ;; + run-agent) + EXTRAS="graph,a2a,agent-claude,knowledge,knowledge-hf,langchain_tool,mempalace" + ;; + evaluation) + EXTRAS="eval" + ;; + a2a) + EXTRAS="a2a" + ;; +esac + +# Manual/skipped examples may also need mem0 / cube when --include-manual is set. +if [[ "$INCLUDE_MANUAL" == true ]]; then + EXTRAS="${EXTRAS},mem0,cube" +fi + +pipeline_uv_install_extras "${EXTRAS}" + prepare_tasks case "$RUN_MODE" in diff --git a/pipeline_test/run_ecosystem_examples.sh b/pipeline_test/run_ecosystem_examples.sh index 8636ee3bf..a17b691f5 100644 --- a/pipeline_test/run_ecosystem_examples.sh +++ b/pipeline_test/run_ecosystem_examples.sh @@ -4,7 +4,45 @@ export DISABLE_TRPC_AGENT_REPORT=true set -e -pip3 install -r pipeline_test/requirements-ecosystem.txt +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +cd "$REPO_ROOT" + +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if ! PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Error: no project virtual environment found (.venv or venv)." >&2 + echo "Create one first, for example: ./build.sh" >&2 + exit 1 +fi + +echo "Using project virtual environment: ${PROJECT_VENV_DIR}" +# shellcheck source=/dev/null +source "${PROJECT_VENV_DIR}/bin/activate" +# export PYTHON_BIN="${REPO_ROOT}/${PROJECT_VENV_DIR}/bin/python" + +# shellcheck source=pipeline_test/_install_deps.sh +source "${SCRIPT_DIR}/_install_deps.sh" + +# A2A + Claude team member examples +pipeline_uv_install_extras "a2a,agent-claude" +pipeline_uv_install_requirements "pipeline_test/requirements-ecosystem.txt" # 启动A2A服务端（后台运行） echo "启动A2A服务端..." @@ -38,4 +76,4 @@ cd - # python3 examples/ecosystem/langchain_knowledge/custom_document_loader.py # python3 examples/ecosystem/langchain_knowledge/custom_retriever.py -# python3 examples/ecosystem/langchain_knowledge/custom_text_splitter.py \ No newline at end of file +# python3 examples/ecosystem/langchain_knowledge/custom_text_splitter.py diff --git a/pipeline_test/run_evaluation_examples.sh b/pipeline_test/run_evaluation_examples.sh index 8d32b6caa..ec2bac0e4 100644 --- a/pipeline_test/run_evaluation_examples.sh +++ b/pipeline_test/run_evaluation_examples.sh @@ -4,6 +4,45 @@ export DISABLE_TRPC_AGENT_REPORT=true set -e +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" +cd "$REPO_ROOT" + +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if ! PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Error: no project virtual environment found (.venv or venv)." >&2 + echo "Create one first, for example: ./build.sh" >&2 + exit 1 +fi + +echo "Using project virtual environment: ${PROJECT_VENV_DIR}" +# shellcheck source=/dev/null +source "${PROJECT_VENV_DIR}/bin/activate" +# export PYTHON_BIN="${REPO_ROOT}/${PROJECT_VENV_DIR}/bin/python" + +# shellcheck source=pipeline_test/_install_deps.sh +source "${SCRIPT_DIR}/_install_deps.sh" + +# AgentEvaluator needs rouge-score / pandas / pytest from [eval] +pipeline_uv_install_extras "eval" + # Evaluation cd examples/evaluation/quickstart && pytest test_quickstart.py -v -s && cd - cd examples/evaluation/webui && pytest test_book_finder.py -v -s && cd - @@ -11,4 +50,4 @@ cd examples/evaluation/callbacks && pytest test_callbacks.py -v -s && cd - cd examples/evaluation/custom_runner && pytest test_custom_runner.py -v -s && cd - cd examples/evaluation/context_messages && pytest test_context_messages.py -v -s && cd - cd examples/evaluation/trace_mode && pytest test_trace_mode.py -v -s && cd - -cd examples/evaluation/pass_at_k && pytest test_pass_at_k.py -v -s && cd - \ No newline at end of file +cd examples/evaluation/pass_at_k && pytest test_pass_at_k.py -v -s && cd - diff --git a/pipeline_test/run_other_examples.sh b/pipeline_test/run_other_examples.sh index 90ffab223..6ec6a2dfd 100644 --- a/pipeline_test/run_other_examples.sh +++ b/pipeline_test/run_other_examples.sh @@ -4,6 +4,35 @@ export DISABLE_TRPC_AGENT_REPORT=true set -e +is_virtualenv_python() { + local python_bin="$1" + [[ -x "${python_bin}" ]] && "${python_bin}" -c \ + 'import sys; raise SystemExit(0 if sys.prefix != sys.base_prefix else 1)' >/dev/null 2>&1 +} + +resolve_project_venv() { + local candidate + for candidate in .venv venv; do + if is_virtualenv_python "${candidate}/bin/python"; then + printf '%s\n' "${candidate}" + return 0 + fi + done + return 1 +} + +PROJECT_VENV_DIR="" +if ! PROJECT_VENV_DIR="$(resolve_project_venv)"; then + echo "Error: no project virtual environment found (.venv or venv)." >&2 + echo "Create one first, for example: ./build.sh" >&2 + exit 1 +fi + +echo "Using project virtual environment: ${PROJECT_VENV_DIR}" +# shellcheck source=/dev/null +source "${PROJECT_VENV_DIR}/bin/activate" +# export PYTHON_BIN="${REPO_ROOT}/${PROJECT_VENV_DIR}/bin/python" + # File Tools cd examples/file_tools/ python3 run_agent.py @@ -30,4 +59,4 @@ python3 examples/session_summarizer/run_agent.py # Tools # python3 examples/tools/mcp_tools/mcp_tools.py -python3 examples/mcp_tools/run_agent.py \ No newline at end of file +python3 examples/mcp_tools/run_agent.py diff --git a/pyproject.toml b/pyproject.toml index 33c466a5e..425ab78f1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -24,9 +24,10 @@ classifiers = [ "Programming Language :: Python :: 3.12", ] dependencies = [ + "python-dotenv", "pydantic>=2.11.3", "openai>=1.66.0", - "mcp>=1.10.1", + "mcp<2.0.0,>=1.10.1", "aiohttp", "httpx>=0.27.0", "httpx-sse>=0.4.0", @@ -34,16 +35,12 @@ dependencies = [ "graphviz", "opentelemetry-sdk", "opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.28.0", - "fastapi>=0.95.0", "uvicorn", - "langgraph", - "langchain>=0.3.27", "tzlocal", "PyMySQL", "aiomysql", "SQLAlchemy", "redis>=6.2.0", - "langchain-deepseek", "docker", "anthropic>=0.72.1", "python-magic>=0.4.27", @@ -60,8 +57,10 @@ dependencies = [ [project.optional-dependencies] ag-ui = [ "ag-ui-protocol>=0.1.8", + "fastapi>=0.95.0", ] langfuse=[ + "fastapi>=0.95.0", "opentelemetry-sdk<2.0.0,>=1.28.0", "opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.28.0", ] @@ -70,10 +69,22 @@ openclaw = [ "aiofiles", "wecom-aibot-sdk-python>=0.1.5", ] +graph = [ + "langgraph>=0.6.0", + "langchain-core>=0.3.27", + "langchain>=0.3.27", + "langchain-openai", +] knowledge = [ - "numpy>=2.2.5", + "langchain>=0.3.27", + "langchain-core>=0.3.27", "langchain_community>=0.3.27", - "langchain_huggingface>=0.1.0" + "langchain-openai", +] +deepseek-langchain = ["langchain-deepseek"] +knowledge-hf = [ + "langchain_huggingface>=0.1.0", + "sentence-transformers>=3.0.0", ] a2a = [ @@ -84,6 +95,7 @@ a2a = [ agent-claude = [ "claude-agent-sdk>=0.1.3,<0.1.64", "cloudpickle>=2.0.0", + "fastapi>=0.95.0", ] eval = [ @@ -101,7 +113,7 @@ optimize = [ mem0 = [ "mem0ai>=1.0.3", - "sentence-transformers", + "sentence-transformers>=3.0.0", ] cube = [ @@ -114,29 +126,23 @@ mempalace = [ langchain_tool = [ "langchain_tavily", - "langchain", - "langchain-core", + "langchain-core>=0.3.27", ] dev = [ - "protobuf>=5.29.5", - "numpy>=2.2.5", "pytest", "pytest-asyncio", - "black", "flake8", "yapf", - "langchain_community>=0.3.27", - "langchain_huggingface>=0.1.0", - "ag-ui-protocol>=0.1.8", - "claude-agent-sdk>=0.1.3,<0.1.64", - "cloudpickle>=2.0.0", - "typer>=0.9.0", ] all = [ "protobuf>=5.29.5", "numpy>=2.2.5", + "fastapi>=0.95.0", + "langgraph>=0.6.0", + "langchain-core>=0.3.27", + "langchain>=0.3.27", "langchain_community>=0.3.27", "langchain_huggingface>=0.1.0", "langchain_tavily", diff --git a/tests/agents/test_optional_graph_dependencies.py b/tests/agents/test_optional_graph_dependencies.py new file mode 100644 index 000000000..97dc06df4 --- /dev/null +++ b/tests/agents/test_optional_graph_dependencies.py @@ -0,0 +1,42 @@ +"""Tests for the optional LangGraph dependency boundary.""" + +import subprocess +import sys + + +def test_core_agent_imports_do_not_require_graph_dependencies(): + script = r""" +import importlib.abc +import sys + + +class BlockGraphImports(importlib.abc.MetaPathFinder): + def find_spec(self, fullname, path=None, target=None): + if fullname.split(".", 1)[0] in {"langgraph", "langchain", "langchain_core"}: + raise ModuleNotFoundError(f"No module named {fullname!r}", name=fullname) + return None + + +sys.meta_path.insert(0, BlockGraphImports()) + +from trpc_agent_sdk.agents import LlmAgent +from trpc_agent_sdk.agents.utils import TRPC_EVENT_MARKER +from trpc_agent_sdk.runners import Runner + +assert LlmAgent is not None +assert Runner is not None +assert TRPC_EVENT_MARKER == "__trpc_event__" + +try: + from trpc_agent_sdk.agents import LangGraphAgent +except ImportError as exc: + assert "trpc-agent-py[graph]" in str(exc) +else: + raise AssertionError("LangGraphAgent import should require the graph extra") +""" + subprocess.run( + [sys.executable, "-c", script], + check=True, + capture_output=True, + text=True, + ) diff --git a/trpc_agent_sdk/agents/__init__.py b/trpc_agent_sdk/agents/__init__.py index bfc1b9426..217bc67ad 100644 --- a/trpc_agent_sdk/agents/__init__.py +++ b/trpc_agent_sdk/agents/__init__.py @@ -9,6 +9,7 @@ and working with TRPC agents. It provides the base agent class, callback filter, multi-agent composition patterns, and all essential type definitions for agent development. """ +from typing import Any from trpc_agent_sdk.configs import RunConfig from trpc_agent_sdk.context import InvocationContext @@ -25,17 +26,48 @@ from ._callback import ToolCallbackFilter from ._chain_agent import ChainAgent from ._cycle_agent import CycleAgent -from ._langgraph_agent import LangGraphAgent from ._llm_agent import LlmAgent from ._parallel_agent import ParallelAgent from ._transfer_agent import TransferAgent from .core import BranchFilterMode from .core import TimelineFilterMode -from .utils import get_agent_context -from .utils import get_agent_context as get_langgraph_agent_context -from .utils import get_langgraph_payload -from .utils import langgraph_llm_node -from .utils import langgraph_tool_node + +_GRAPH_EXPORTS = { + "LangGraphAgent", + "get_agent_context", + "get_langgraph_agent_context", + "get_langgraph_payload", + "langgraph_llm_node", + "langgraph_tool_node", +} + + +def __getattr__(name: str) -> Any: + """Load LangGraph integrations only when their public API is requested.""" + if name not in _GRAPH_EXPORTS: + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + try: + if name == "LangGraphAgent": + from ._langgraph_agent import LangGraphAgent + + value = LangGraphAgent + else: + from . import utils + + source_name = "get_agent_context" if name == "get_langgraph_agent_context" else name + value = getattr(utils, source_name) + except ModuleNotFoundError as exc: + missing = exc.name or "" + if missing == "langgraph" or missing.startswith( + "langgraph.") or missing == "langchain_core" or missing.startswith("langchain_core."): + raise ImportError(f"{name} requires the optional 'graph' dependencies. " + 'Install them with: pip install "trpc-agent-py[graph]"') from exc + raise + + globals()[name] = value + return value + __all__ = [ "RunConfig", diff --git a/trpc_agent_sdk/agents/utils/__init__.py b/trpc_agent_sdk/agents/utils/__init__.py index fd8d2e135..dd81aaa67 100644 --- a/trpc_agent_sdk/agents/utils/__init__.py +++ b/trpc_agent_sdk/agents/utils/__init__.py @@ -6,16 +6,8 @@ """ TRPC Agent Context Utilities Module. """ +from typing import Any -from ._langgraph import AGENT_CTX_KEY -from ._langgraph import CHUNK_KEY -from ._langgraph import LANGGRAPH_KEY -from ._langgraph import STREAM_MODE_KEY -from ._langgraph import TRPC_AGENT_KEY -from ._langgraph import get_agent_context -from ._langgraph import get_langgraph_payload -from ._langgraph import langgraph_llm_node -from ._langgraph import langgraph_tool_node from ._langgraph_event_writer import LANGGRAPH_EVENT_TYPE from ._langgraph_event_writer import LangGraphEventType from ._langgraph_event_writer import LangGraphEventWriter @@ -24,6 +16,39 @@ from ._langgraph_event_writer import get_event_type from ._langgraph_event_writer import is_trpc_event_chunk +_LANGGRAPH_EXPORTS = { + "AGENT_CTX_KEY", + "CHUNK_KEY", + "LANGGRAPH_KEY", + "STREAM_MODE_KEY", + "TRPC_AGENT_KEY", + "get_agent_context", + "get_langgraph_payload", + "langgraph_llm_node", + "langgraph_tool_node", +} + + +def __getattr__(name: str) -> Any: + """Load LangGraph context helpers only when explicitly requested.""" + if name not in _LANGGRAPH_EXPORTS: + raise AttributeError(f"module {__name__!r} has no attribute {name!r}") + + try: + from . import _langgraph + except ModuleNotFoundError as exc: + missing = exc.name or "" + if missing == "langgraph" or missing.startswith( + "langgraph.") or missing == "langchain_core" or missing.startswith("langchain_core."): + raise ImportError(f"{name} requires the optional 'graph' dependencies. " + 'Install them with: pip install "trpc-agent-py[graph]"') from exc + raise + + value = getattr(_langgraph, name) + globals()[name] = value + return value + + __all__ = [ "AGENT_CTX_KEY", "CHUNK_KEY", diff --git a/trpc_agent_sdk/agents/utils/_langgraph_event_writer.py b/trpc_agent_sdk/agents/utils/_langgraph_event_writer.py index ef4940fab..3801079c5 100644 --- a/trpc_agent_sdk/agents/utils/_langgraph_event_writer.py +++ b/trpc_agent_sdk/agents/utils/_langgraph_event_writer.py @@ -15,8 +15,6 @@ from trpc_agent_sdk.events import Event from trpc_agent_sdk.log import logger -from ._langgraph import get_agent_context - # Marker to identify trpc Events in LangGraph custom stream TRPC_EVENT_MARKER = "__trpc_event__" @@ -105,6 +103,8 @@ def from_config(cls, writer: Any, config: Dict[str, Any]) -> "LangGraphEventWrit Raises: ValueError: If InvocationContext is not found in config """ + from ._langgraph import get_agent_context + ctx = get_agent_context(config) return cls(writer, ctx) diff --git a/trpc_agent_sdk/dsl/graph/_node_action/_knowledge.py b/trpc_agent_sdk/dsl/graph/_node_action/_knowledge.py index 0399f781d..621ccd2f5 100644 --- a/trpc_agent_sdk/dsl/graph/_node_action/_knowledge.py +++ b/trpc_agent_sdk/dsl/graph/_node_action/_knowledge.py @@ -4,15 +4,19 @@ # # tRPC-Agent-Python is licensed under Apache-2.0. """Knowledge search node action executor.""" +from __future__ import annotations from typing import Any from typing import Callable from typing import Optional +from typing import TYPE_CHECKING from typing import Union from trpc_agent_sdk.context import InvocationContext from trpc_agent_sdk.log import logger -from trpc_agent_sdk.server.knowledge.tools import LangchainKnowledgeSearchTool + +if TYPE_CHECKING: + from trpc_agent_sdk.server.knowledge.tools import LangchainKnowledgeSearchTool from .._constants import STATE_KEY_LAST_RESPONSE from .._constants import STATE_KEY_NODE_RESPONSES diff --git a/trpc_agent_sdk/dsl/graph/_state_graph.py b/trpc_agent_sdk/dsl/graph/_state_graph.py index ff53076b4..95d43b5ba 100644 --- a/trpc_agent_sdk/dsl/graph/_state_graph.py +++ b/trpc_agent_sdk/dsl/graph/_state_graph.py @@ -8,12 +8,14 @@ This module provides StateGraph and CompiledStateGraph classes built on top of LangGraph with TRPC-Agent-specific features. """ +from __future__ import annotations import inspect from typing import Any from typing import Callable from typing import Hashable from typing import Optional +from typing import TYPE_CHECKING from typing import Type from typing import Union @@ -27,10 +29,12 @@ from trpc_agent_sdk.code_executors import BaseCodeExecutor from trpc_agent_sdk.context import InvocationContext from trpc_agent_sdk.models import LLMModel -from trpc_agent_sdk.server.knowledge.tools import LangchainKnowledgeSearchTool from trpc_agent_sdk.tools import MCPToolset from trpc_agent_sdk.types import GenerateContentConfig +if TYPE_CHECKING: + from trpc_agent_sdk.server.knowledge.tools import LangchainKnowledgeSearchTool + from ._callbacks import NodeCallbackContext from ._callbacks import NodeCallbacks from ._callbacks import merge_callbacks diff --git a/trpc_agent_sdk/knowledge/_knowledge.py b/trpc_agent_sdk/knowledge/_knowledge.py index e996739ad..acc92a751 100644 --- a/trpc_agent_sdk/knowledge/_knowledge.py +++ b/trpc_agent_sdk/knowledge/_knowledge.py @@ -12,10 +12,15 @@ from typing import List from typing import Optional -from langchain_core.documents import Document -from langchain_core.messages import BaseMessage from pydantic import BaseModel +try: + from langchain_core.documents import Document + from langchain_core.messages import BaseMessage +except ImportError: + Document = Any + BaseMessage = Any + from trpc_agent_sdk.context import AgentContext from trpc_agent_sdk.types import Part diff --git a/trpc_agent_sdk/server/knowledge/langchain_knowledge.py b/trpc_agent_sdk/server/knowledge/langchain_knowledge.py index c75be5108..7e9972ca8 100644 --- a/trpc_agent_sdk/server/knowledge/langchain_knowledge.py +++ b/trpc_agent_sdk/server/knowledge/langchain_knowledge.py @@ -20,17 +20,10 @@ from langchain_core.prompt_values import PromptValue from langchain_core.prompts.base import BasePromptTemplate from langchain_core.retrievers import BaseRetriever +from langchain_core.runnables import Runnable as Chain from langchain_core.runnables import RunnableConfig from langchain_core.vectorstores import VectorStore -# Version compatibility: Support both LangChain 0.3.x and 1.x.x -# In LangChain 1.x, Chain is deprecated in favor of Runnable -try: - from langchain_core.runnables import Runnable as Chain -except ImportError: - # Fallback to Chain for LangChain 0.3.x - from langchain.chains.base import Chain - from trpc_agent_sdk.context import AgentContext from trpc_agent_sdk.knowledge import KnowledgeBase from trpc_agent_sdk.knowledge import SearchDocument