内容
Langfuse 代理
## MCP | 代理
CP 服务器](https://badge.mcpx.dev?type=server 'MCP 服务器')
PI - 下载次数](img.shields.io/pypi/dd/langfuse-agent)
*0.33.0*
> **文档** —部署、使用 API、CLI 和 MCP 接口，以及 Lang 平台的配置指南，请参阅
> [官方https://knuck.github.io/langfuse。
---
## 概述
**Langfuse是一个生产级别的代理和模型上下文协议（M服务器，旨在直接与 Langfuse LLM 工程观察性平台交互。它使代理模型能够查询、创建和管理可观察性跟踪、数据集、提示模板和系统配置。
---
## 主要功能
- **合并的动作路由 MCP 工具：** 通过将 80 多个方法分组为 4 个优化的、可切换的工具模块，最大限度地减少 LLM 上下文中的令牌开销并消除工具膨胀。
- **企业级安全性：** 完全支持 Eunomia 策略、OIDC 令牌委托和粒度执行上下文跟踪。
- **集成的图代理：** 内置的 Pydantic AI 代理，支持代理控制协议（ACP）和标准 Web 接口（AG-UI）。
- **原生遥测和跟踪：** 开箱即用的 OpenTelemetry 导出和原生的 Langfuse 跟踪跟踪每个跟踪和跨度。
---
## CLI 或 API
此代理包装了 Langfuse API。您可以通过编程方式或通过其集成的执行入口与它交互。
有关如何使用底层 API 包装器、扩展模式绑定和开发人员 SDK 引用，请参阅 [docs/index.md](docs/index.md)。
---
## MCP
该服务器使用动态动作路由工具来优化令牌开销并最大限度地提高 IDE 兼容性。
### 可用的 MCP 工具
自动生成 - 请勿在以下标记之间编辑。
<!-- MCP-TOOLS-TABLE:START -->
| MCP 工具 | 切换环境变量 | 描述 |
|----------|----------------|-------------|
|fuse_datasets `LANGFUSE_DATASETSTOOL` | 执行use_datasets 操作。 |
| `langfuse | `LANGFUSE_MANAGEMENTTOOL` | 执行 lang_management 操作。 |
| `langfuse_observability` | `LANGFUSE_OBSERVABILITYTOOL` | 执行 langfuse_observability 操作。 |
langfuse_prompts_models `LANGS_MODELSTOOL` | 执行 langfpts_models 操作。 |
_4 个动作路由工具（默认 `MCP_TOOL_MODE=condensed`）。非其切换为 false，否则都是启用的 `MCP_TOOL_MODE=verbose`（或 `）以获取 1:1 的每个操作曲面。自动生成 - 请勿编辑。_
<!-- MCP-TOOLS-TABLE:END -->
详细的工具模式、参数形状和验证约束保存在 [docs/mcp.md](docs/mcp.md) 中。
### 动态工具选择和可见性
MCP 服务器支持动态工具集选择和运行时可见性过滤。这样，您可以限制暴露的工具集，以防止 LLM 的上下文窗口爆炸。
您可以通过多个输入通道配置工具过滤：
- **CLI 参数：** 在启动时传递 `--tools` 或 `--toolsets`（或其禁用对应项 `--disabled-tools` 和 `--disabled`）。
- **环境** 定义标准：
- `_TOOLS`MCP_DISABLED_TOOLS`
- `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS`
- **头：** 在传输初始化期间传递自定义头：
- `x-mcp-enabled-tools` / `x-mcp-disabled-tools`
- `x-mcp-enabled-tags` / `x-mcp-disabled-tags`
- **HTTP SSE 请求查询参数：** 直接将查询参数追加到传输连接 URL：
- `?tools=tool1,tool2`
- `?tags=tag1`
当提供查询参数时，LLM-free **知识图谱解析层**（使用 `DynamicToolOrchestrator`）将查询意图与已知的工具标签、名称或描述进行匹配，并具有安全的回退和自动的 24 小时后台缓存刷新。
---
### MCP 配置示例
> **安装精简的 `[mcp]` 额外组件。** 以下所有示例均安装
> `langfuse-agent[mcp]` — MCP 服务器额外组件，仅拉取 FastMCP /工具包（ities[mcp]`）。它故意 **排除** 了沉重的
> 代理运行时（认知图引擎，`pydantic-ai`，`dspy`，`llama-index`，`tree-sitter`），因此 `uvx容器安装明显更小、更快。
> 您需要集ydantic AI ，才使用完整的 `[agent]` 额外组件（阅 [安装](#）。
#### stdio 传输（推荐用于本地 IDE，例如 Cursor、Cl）
在 `uvx` 上通过 `mcp 配置 MCP 服务器：
```json
{
mcpServers": {
"langfuse-agent": {
"command": "uvx",
"args": [
"--from",
"langfuse-agent[mcp]",
"langfuse-mcp ],
"env": {
"LANGFUSE_BASE_URL": "http:8080",
"LANGFUSE_TOKEN": "your_token_h }
}
}
}
```
#### 流式 HTTP 传输（推荐用于生产部署）
将服务器作为长时间运行的流式 HTTP 服务运行：
```json
{
"mcpServers": {
"langfuse-agent": {
"url": "http://localhost:8004/langfuse-agent/mcp"
}
}
}
```
通过 Docker 部署流式 HTTP 服务器：
```docker run -d \
--name langfuse-agent-mcp \
-p 8004:8004 \
-e TRANSPORT=streamable-http \
-e PORT=8004 \
-e LANGFUSE_BASE_URL="http://your-langfuse-instance:8080" \
e LANGFUSE_TOKEN="your_token" \
ucklessg1/langfuse-agent:mcp> `:mcp` 标签是 **精简 服务器镜像**（从
> `docker/D --target mcp` 构建，安装fuse-agent[mcp]`）。默认
>` 标签是 **完整的**（` agent`，`langfuse-agent[agent> 还捆绑了 Pydantic AI 代理和认知图引擎 - 在运行 `lang-agent`（代理）时使用，而不是仅使用 MCP 服务器。请参阅
> [容器镜像](#容器cp-vs-agent)。
---
<!-- BEGIN GENERATED: additional-deployment-options -->
### 附加部署选项
`langfuse-agent` 还可以作为 **本地容器** / Podman / `uv`）运行或远程部署**。
[部署指南://knuckles-team.github.io/langfuse/) 提供了所有传输的完整、可复制的 `mcp_config.json` — **stdio**streamable-http**、
**本地容器 / uv** 和 **远程 URL **本地容器 / — 通过 `uvx`、 `docker run` 或 `podman 从 `mcp_config.json` 启动服务器，或通过 URL 指向本地 HTTP 容器。
- **远程 URL** — 使用 `"url"` 键连接到在 Caddy 后部署，位于
`http://langfcp.arpa/mcp`。
<!-- END GENERATED-deployment-options -->
代理
该包含一个完全集ydantic AI 图通过 **代理控制协议（ACP）**，并与 **代理 Web UI（AG-UI 和终端界面无。
### 运行代理 CLI
要启动交互式命令行代理：
```# 设置凭证
export LANGFUSE_BASE_URL="http://localhost:8080"
export LANGF="your_token"
# 运行代理服务器
langfuse-agent --provider openai --model-id gpt-4o
```
### Docker Compose 协调
以下 `docker/agent.compose.yml` 配置代理、Web UI 和终端界面：
```yaml
version: '3.8'
services:
langfuse-agent:
image: knucklessg1/langfuse-agent:mcp
container_name: langfuse-agent-mcp
hostname: langfuse-agent-mcp
restart: always
env_file:
- ../.env
environment:
- PYTHONUNBUFFERED=1
- HOST.0.0.0
- PORT=8004
- TRANSPORT=streamable-http
ports:
- "8004:8004"
healthcheck:
test: ["CMD",3", "-cimport urllib.request; urllib.request.urlopen('http://localhost:8004/health')"]
interval: 30s
timeout: 10s
retries: 3
start_period: 10s
langfuse-agent-agent:
image: knucklessgfuse-agent:latest
container_name: lang-agent-agent
hostname: langfuse
restart: always
depends_on:
- langfusecp
:
- ../.env
command: [ "langfuse-agent" ]
environment:
- PYTHONUNBUFFERED=1
- HOST=0.0.0.0
- PORT=9004
- MCP_URL=http://use-agent-mcp:8004/mcp
- PROVIDER=${PROVIDER:-openai}
- MODEL_ID=${MODEL_ID:-gpt-4o}
- ENABLE_WEB_UI=True
- ENABLE_OTEL=True
ports:
- ":9004"
healthcheck:
test: ["CMD", "", "-c", "import urllib.request; urllib.request.urlopen('http:9004/health')"]
interval:s
timeout: 10s
retries: 3
start_period: 10s
```
有关图节点架构解释、自定义技能配置和代理跟踪指南，请参阅 [docs/agent.md](docs/agent.md)。
---
## 安全性和治理
直接在企业就绪的 [`agent-utilities`](https://github.com/Knuckles-Team/agent-utilities) 核心上构建，支持标准的 安全参数：
### 访问控制和策略强制执行
- **Eunomia 策略：** 细粒度、基于策略的工具授权。支持 `none`、本地 `embedded`（`mcp_policies）或集中式 `remote` 模式。
- **OIDC 令牌委托：** 符合 RFC 8693 令牌交换，用于从 Web UI / ACP → 代理 → MCP 流动身份验证用户凭证。
- **作用域凭证：** 执行上下文运行仅限于特定的调用者身份 运行时安全网格
| 功能 | 功能描述 | 启用状态 |
|---------|---------------|------------|
| **工具防护** | 敏感性检查，人工验证 | 默认启用 |
| **提示注入防御** | 输入扫描、重复监测和递归循环阻止 | 默认启用 |
| **上下文安全防护** | 卡顿检测器和上下文溢出预警 | 默认启用 |
---
## 配置和环境变量
代理可以通过 `.env` 文件完全配置。以下是所有支持的变量列表：
### 核心 API 和凭证
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `LANGFUSE_BASE_URL` | Langfuse 实例基本 URL。 | `https://cloud.langfuse.com` |
| `LANGFUSE_PUBLIC_KEY` | Langfuse 公共 API 密钥。 | `""` |
| `LANGFUSE_SECRET_KEY` | Langfuse 机密 API 密钥。 | `""` |
| `LANGFUSE_TOKEN` | 综合身份验证令牌。 | `""` |
### 服务器配置
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `HOST` | 服务器绑定到的主机名/地址。 | `0.0.0.0` |
| `PORT` | 服务器监听的端口。 | `8004` |
| `TRANSPORT` | 通信协议（`stdio`、`stream`、`sse`）。 | `stdio` |
| `AUTH_TYPE` | 服务器身份验证策略（`key`、`delegated`、`none`）。 | `key` |
### 代理自定义
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `DEFAULT_AGENT_NAME` | Pydantic AI 图代理的自定义名称。 | `"Langfuse 代理"` |
| `AGENT_DESCRIPTION` | 代理责任的简要描述。 | `"用于 Langf代理操作的 AI 代理。"` |
|ENT_SYSTEM_PROMPT` | 代理的自定义系统。 | `""` |
### 工具切换开关
可以启用或禁用各个工具模块，以最小化客户端上下文大小。
这些名称与上方 [可用 MCP 工具-mcp-tools“切换环境变量”列匹配：
FUSE_OBSERVABILITYTOOL`（默认值：`True`）：切换观察/跟踪工具。
- `LANGFUSE_DATASETSTOOL`（默认值：`True`）：切换数据集和注释队列工具。
- `LANGFUSE_PROMPTS_MODELSTOOL`（默认值：`True`）：切换提示模板和模型连接工具。
- `LANG_MANAGEMENTTOOL`（默认值：`True`）：切换评论、SCIM 和项目管理工具。
---
## 安装
选择与您要运行的内容匹配的额外组件：
| 额外组件 | 使用场景 |
|-------|----------|----------|
| `langfuse-agent[mcp]` | 仅限精简 MCP 服务器（`agent-utilities[mcp]` — FastMCP/FastAPI） | 您仅运行 **MCP 服务器**（最小安装/镜像） |
| `langfuse-agent[agent]` | 完整代理运行时（`agent-utilities[agent,logfire]` — Pyd + 认知图引擎） | 您运行 **集成代理** |
| `langfuse-agent[all]` | 所有内容（`mcp` + `agent` + `logfire`） | 开发/两者 |
```bash
# 仅限 MCP 服务器（推荐用于工具托管 — 精简依赖）
# 使用uv pip安装“langfuse-agent[mcp]”
uv pip install "langfuse-agent[mcp]"
# 完整代理运行时（Pydantic AI + 认知图引擎）
uv pip install "langfuse-agent[agent]"
# 所有内容（开发）
uv pip install "langfuse-agent[all]" # 或：python -m pip install "langfuse-agent[all]"
```
### 容器镜像（`:mcp` vs `:agent`）
一个多阶段的 `docker/Dockerfile` 构建了两个合适大小的镜像，通过 `--target` 选择：
| 镜像标签 | 构建目标 | 内容 | 入口点 |
|-----------|--------------|----------|------------|
| `knucklessg1/langfuse-agent:mcp` | `--target mcp` | `langfuse-agent[mcp]` — **精简**，无引擎/`pydantic-ai`/`dspy`/`llama-index`/`tree-sitter` | `langfuse-mcp` |
| `knucklessg1/langfuse-agent:latest `--target agent`（默认） | `langfuse-agent[agent **完整** 代理运行时 + 认知图引擎 | `langfuse |
```bash
docker build --target mcp -t knuckless/langfuse-agent:mcp docker/ # 精简MCP服务器
docker build --target agent -t knucklessg1/langfuse-agent:latest docker/ # 完整代理
图数据库（`epistemic-graph`）
**完整代理**（`[agent]` /`）嵌入了 **认知图** 引擎（通过 `agent-utilities[agent]` 传递依赖）。
对于生产环境 - 或在多个代理之间共享一个知识图谱 - 以 **独立的认知容器** 运行 **认知图**，并将代理指向它，而不是嵌入它。
部署配方（单节点 + Ra），连接配置和完整的数据库架构（带有图表）请参阅认知图部署指南](https://knuck.githubistemic/)简的 `[mcp]` 服务器 **不** 需要数据库## 文档
完整的文档已发布为
[官方文档站点](https://les-team.github.io/langfuse-agent/)，并
是安装、日常操作的推荐参考。
| 页面 | 内容 |
|---|---|
| [安装](https://knuckles-team.github.io/langfuse-agent/installation/)、源码、额外依赖、预构建镜像 |
| [部署](https://knuckles-team.github.io/langfuse-agent/deployment/) | 运行MCP和代理服务器、Compose、Caddy + Technitium、环境变量配置 |
| [使用](https://knuckles-team.github.io/langfuse-agent/usage/) | MCP工具、`LangfuseApi` 客户端、CLI |
| [后端平台](https://knuckles-team.github.io/langfuse-agent/platform/) | 使用Docker部署 Langfuse |
| [概述](https://knuckles-team.github.io/langfuse-agent/overview/) | 完整的工具曲面和生态系统角色 |
| [概念](https://knuckles-team.github.io/langfuse-agent/concepts/) | 概念注册表 (`CONCEPT:LF-*`) |
---
## 仓库所有者
<img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessshow_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />
---
## 贡献
欢迎贡献！请通过在提交拉取请求前执行本地检查来确保代码质量：
- 使用 `ruff format .` 格式化代码
- 使用 `ruff check .` 检查代码
- 使用 `mypy .` 验证类型安全性
- 使用 `pytest` 执行测试套件
<!-- BEGIN agent-os-genesis-deploy (generated; do not edit between markers) -->
## 使用 `agent-os-genesis` 部署
该软件包可以通过 **`agent-os-genesis`** 通用技能（其*单软件包部署模式*）为您提供配置引导：它会选择您的安装方法，为 OpenBao/Vault（或 `.env`）植入机密，信任您的企业 CA，注册 MCP 服务器，并验证它 — 与建立整个 Agent OS 的相同机制，仅限于此软件包。要求您的代理 **"使用 agent-os-genesis 部署 `langfuse-agent`"**。
| 安装模式 | 命令 |
|------|---------|
| 裸金属，生产环境（PyPI） | `uvx langfuse-mcp` · 或 `uv tool install langfuse-agent` |
| 裸金属，开发环境（可编辑） | `uv pip install -e ".[all]"` · 或 `pip install -e ".[all]"` |
| 容器，生产环境 | 通过 docker-compose / swarm / podman / podman-compose / kubernetes 部署 `knucklessg1/langfuse-agent:latest` |
| 容器，开发环境（可编辑） | 部署 `docker/compose.dev.yml`（源代码挂载在 `/src`；重启时编辑生效） |
机密信息通过 `vault_sync` 读取现有并植入 — 您只需为缺少的机密信息进行提示。
<!-- END agent-os-genesis-deploy -->
## 环境变量
<!-- ENV-VARS-TABLE:START -->
#### 软件包环境变量
| 变量 | 示例 | 描述 |
|----------|---------|-------------|
| `HOST` | `0.0.0.0` | |
| `PORT` | `8004` | |
| `TRANSPORT` | `stdio` | 选项：stdio, streamable-http, sse |
| `ENABLE_OTEL` | `True` | |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:8080/api/public/otel` | |
| `OTEL_EXPORTER_OTLP_PUBLIC_KEY` | `pk-...` | |
| `OTEL_EXPORTER_OTLP_SECRET_KEY` | `sk-...` | |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | |
| `EUNOMIA_TYPE` | `none` | 选项：none, embedded, remote |
| `EUNOMIA_POLICY_FILE` | `mcp_policies.json` | |
| `EUNOMIA_REMOTE_URL` | `http://eunomia-server:8000` | |
| `LANGFUSE_BASE_URL` | `http://localhost:8080` | |
| `LANGFUSE_PUBLIC_KEY` | `your_public_key_here` | |
| `LANGFUSE_SECRET_KEY` | `your_secret_key_here` | |
| `LANGFUSE_TOKEN` | `your_token_here` | |
| `AUTH_TYPE` | `key` | 选项：key, delegated, none |
| `DEFAULT_AGENT_NAME` | `"Langfuse 代理"` | |
| `AGENT_DESCRIPTION` | `"用于 Langfuse 代理操作的 AI 代理."` | |
| `AGENT_SYSTEM_PROMPT` | `""` | |
| `LANGFUSE_OBSERVABILITYTOOL` | `True` | MCP 工具表（压缩的操作路由表面）。 |
| `LANGFUSE_DATASETSTOOL` | `True` | |
| `LANGFUSE_PROMPTS_MODELSTOOL` | `True` | |
| `LANGFUSE_MANAGEMENTTOOL` | `True` | |
#### 继承的 agent-utilities 变量（适用于每个连接器）
| 变量 | 示例 | 描述 |
|----------|---------|-------------|
| `MCP_TOOL_MODE` | `condensed` | 工具表面：`condensed` | `verbose` | `both` |
| `MCP_ENABLED_TOOLS` | — | 以逗号分隔的工具允许列表 |
| `MCP_DISABLED_TOOLS` | — | 以逗号分隔的工具拒绝列表 |
| `MCP_ENABLED_TAGS` | — | 以逗号分隔的标签允许列表 |
| `MCP_DISABLED_TAGS` | — | 以逗号分隔的标签拒绝列表 |
| `MCP_CLIENT_AUTH` | — | 输出 MCP 认证（`oidc-client-credentials` 用于 fleet 调用） |
| `OIDC_CLIENT_ID` | — | OIDC 客户端 ID（服务账户认证） |
| `OIDC_CLIENT_SECRET` | — | OIDC 客户端密钥（服务账户认证） |
| `DEBUG` | `False` | 详细日志记录 |
| `PYTHONUNBUFFERED` | `1` | 无缓冲 stdout（推荐在容器中使用） |
| `MCP_URL` | `http://localhost:8000/mcp` | 代理连接到的 MCP 服务器的 URL |
| `PROVIDER` | `openai` | 代理的 LLM 提供商 |
| `MODEL_ID` | `gpt-4o` | 代理的模型 ID |
| `ENABLE_WEB_UI` | `True` | 提供 AG-UI Web 界面 |
_23 个软件包变量 + 14 个继承变量。自动从 `.env.example` 和共享的 agent-utilities 集生成 — 请勿编辑。_
<!-- ENV-VARS-TABLE:END -->
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器