Skip to content

用于 ADK 的 Chroma MCP 工具

Supported in ADKPythonTypeScript

Chroma MCP 服务器 将你的 ADK 智能体连接到 开源向量嵌入数据库 Chroma。此集成使你的智能体能够创建集合、存储文档，并利用语义搜索、全文搜索和元数据过滤来检索信息。

使用场景

  • 智能体的语义记忆：存储对话上下文、事实或学习到的知识，智能体随后可以通过自然语言查询来检索。

  • 知识库检索：通过存储文档并检索相关的上下文，构建用于生成精准回答的检索增强生成 (RAG) 系统。

  • 跨会话的持久上下文：在不同对话之间维护长期记忆，允许智能体引用过去的交互记录和积累的知识。

先决条件

  • 本地存储：需要一个用于持久化数据的目录路径。
  • Chroma Cloud：需要拥有包含租户 ID、数据库名称和 API 密钥的 Chroma Cloud 账户。

在智能体中使用

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

# 对于本地存储，请使用：
DATA_DIR = "/path/to/your/data/directory"

# 对于 Chroma Cloud，请使用：
# CHROMA_TENANT = "你的租户ID"
# CHROMA_DATABASE = "你的数据库名称"
# CHROMA_API_KEY = "你的API密钥"

root_agent = Agent(
    model="gemini-flash-latest",
    name="chroma_agent",
    instruction="帮助用户通过语义搜索存储并检索信息",
    tools=[
        McpToolset(
            connection_params=StdioConnectionParams(
                server_params=StdioServerParameters(
                    command="uvx",
                    args=[
                        "chroma-mcp",
                        # 对于本地存储，请使用：
                        "--client-type",
                        "persistent",
                        "--data-dir",
                        DATA_DIR,
                        # 对于 Chroma Cloud，请使用：
                        # "--client-type",
                        # "cloud",
                        # "--tenant",
                        # CHROMA_TENANT,
                        # "--database",
                        # CHROMA_DATABASE,
                        # "--api-key",
                        # CHROMA_API_KEY,
                    ],
                ),
                timeout=30,
            ),
        )
    ],
)

import { LlmAgent, MCPToolset } from "@google/adk";

// 对于本地存储，请使用：
const DATA_DIR = "/path/to/your/data/directory";

// 对于 Chroma Cloud，请使用：
// const CHROMA_TENANT = "你的租户ID";
// const CHROMA_DATABASE = "你的数据库名称";
// const CHROMA_API_KEY = "你的API密钥";

const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "chroma_agent",
    instruction: "帮助用户通过语义搜索存储并检索信息",
    tools: [
        new MCPToolset({
            type: "StdioConnectionParams",
            serverParams: {
                command: "uvx",
                args: [
                    "chroma-mcp",
                    // 对于本地存储，请使用：
                    "--client-type",
                    "persistent",
                    "--data-dir",
                    DATA_DIR,
                    // 对于 Chroma Cloud，请使用：
                    // "--client-type",
                    // "cloud",
                    // "--tenant",
                    // CHROMA_TENANT,
                    // "--database",
                    // CHROMA_DATABASE,
                    // "--api-key",
                    // CHROMA_API_KEY,
                ],
            },
        }),
    ],
});

export { rootAgent };

可用工具

集合管理

工具 描述
chroma_list_collections 列出所有集合，支持分页
chroma_create_collection 创建带有可选 HNSW 配置的新集合
chroma_get_collection_info 获取集合的详细信息
chroma_get_collection_count 获取集合中的文档数量
chroma_modify_collection 修改集合名称或元数据
chroma_delete_collection 删除集合
chroma_peek_collection 查看集合中的部分文档样本

文档操作

工具 描述
chroma_add_documents 添加带有可选元数据和自定义 ID 的文档
chroma_query_documents 使用带高级过滤器的语义搜索查询文档
chroma_get_documents 按 ID 或过滤器检索文档，支持分页
chroma_update_documents 更新现有文档的内容、元数据或向量嵌入
chroma_delete_documents 从集合中删除指定文档

配置

Chroma MCP 服务器支持多种客户端类型，以满足不同需求：

客户端类型

客户端类型 描述 关键参数
ephemeral 内存存储，重启即清除。适用于快速测试。 无（默认）
persistent 本地机器上的文件持久化存储 --data-dir
http 连接到自托管的 Chroma 服务器 --host, --port, --ssl, --custom-auth-credentials
cloud 连接到 Chroma Cloud (api.trychroma.com) --tenant, --database, --api-key

环境变量

你也可以通过环境变量配置客户端。命令行参数的优先级高于环境变量。

变量 描述
CHROMA_CLIENT_TYPE 客户端类型：ephemeral、persistent、http 或 cloud
CHROMA_DATA_DIR 持久化本地存储的路径
CHROMA_TENANT Chroma Cloud 的租户 ID
CHROMA_DATABASE Chroma Cloud 的数据库名称
CHROMA_API_KEY Chroma Cloud 的 API 密钥
CHROMA_HOST 自托管 HTTP 客户端的主机名
CHROMA_PORT 自托管 HTTP 客户端的端口号
CHROMA_SSL 启用 HTTP 客户端的 SSL（true 或 false）
CHROMA_DOTENV_PATH .env 文件的路径（默认为 .chroma_env）

其他资源