AI导哈

LLM编排服务

Agent Gateway是一个模块化、兼容OpenAI的编排服务，通过OpenAI Agents SDK将聊天UI连接到本地和云端的LLM后端（如OpenAI、LM Studio、Ollama、vLLM）。

  • by SATUNIX
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 SATUNIX/agent-gateway

使用说明

代理网关

代理网关 是模块化的， OpenAI兼容编排服务 它通过以下方式将您的聊天UI连接到本地和基于云的LLM后端（OpenAI、LM Studio、Ollama、vLLM） OpenAI代理SDK. 将标准SDK代理放入 src/agents/<Name>/agent.py，网关会自动将其公开为 /v1/chat/completions 模型——包括路由、工具、可观察性和安全性。

📚 目录

🚀 亮点

能力 描述
OpenAI兼容的API /v1/chat/completions （使用流式SSE）和代理、上游、工具和安全的管理端点。
插入式SDK代理 代理人 src/agents/** 自动注册为模型，无需进行YAML编辑。支持挂钩、交接、护栏和结构化输出。
工具 用于本地Python、HTTP和MCP提供商的集中式工具/MCP管理器。包括 use_gateway_tool() shim，以便SDK代理可以重用网关工具。
路由 命名空间感知注册表使用每个代理的执行策略将模型映射到上游提供者（OpenAI、LM Studio、Ollama等）。
安全 API密钥、ACL、速率限制、工具允许列表、模块允许/拒绝列表和夜间审核脚本。
可观测性 结构化日志、Prometheus指标、请求ID和可视化仪表板（请参阅 docs/systems/observability.md).
包装 多级Dockerfile、Docker Compose堆栈、SBOM生成、CI/CD管道和操作员运行手册。

⚡ 快速开始

Linux/macOS

git clone https://github.com/<org>/agent-gateway.git
cd agent-gateway
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
cp src/config/security.yaml src/config/security.local.yaml
export GATEWAY_SECURITY_CONFIG=src/config/security.yaml
export PYTHONPATH=src
uvicorn api.main:app --reload

访问：

  • http://127.0.0.1:8000/docs → OpenAPI浏览器
  • http://127.0.0.1:8000/v1/models → 已发现的代理（使用 x-api-key)

视窗

git clone https://github.com/<org>/agent-gateway.git
cd agent-gateway
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install -r requirements.txt
setx GATEWAY_SECURITY_CONFIG "%CD%\src\config\security.yaml"
set PYTHONPATH=%CD%\src
uvicorn api.main:app --reload

💡 提示： 集 GATEWAY_AGENT_AUTO_RELOAD=1 在开发过程中，为YAML和插入式模块启用热重载。
🔁 观看模式： 安装可选依赖项(pip install "agent-gateway[watch]" 或 pip install watchfiles)并设置 GATEWAY_AGENT_WATCH=1 在文件处于以下状态时自动重新加载代理 src/agents/** 改变。

🧩 插入式代理工作流

  1. 编写SDK代理 在...之下 src/agents/<AgentName>/agent.py:

    from agents import Agent, function_tool

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny"

agent = Agent(name="Weather Agent", instructions="Always respond with weather.", tools=[get_weather])

  2. 运行网关

    PYTHONPATH=src uvicorn api.main:app --reload

  3. 列出型号

    curl -H "x-api-key: dev-secret" http://localhost:8000/v1/models

  4. 与客服聊天

    {"model": "default/weatheragent", "messages": [{"role": "user", "content": "Weather in Tokyo"}]}

  5. 可选： 使用 use_gateway_tool() 从以下位置包装条目 src/config/tools.yaml 用于集中式日志记录和ACL。

示例（混合使用本机+网关工具）：

from agents import Agent, function_tool
from sdk_adapter.gateway_tools import use_gateway_tool

@function_tool
def summarize(text: str) -> str:
    return text[:120] + "..."

http_echo = use_gateway_tool("http_echo")

agent = Agent(
    name="SampleAgent",
    instructions="Use summarize() for local context and http_echo for diagnostics.",
    tools=[summarize, http_echo],
)

看 docs/guides/DropInAgentGuide.md 用于惯例、固定装置和故障排除。

⚙️ 配置和文件

文件 目的
src/config/agents.yaml 声明性代理注册表（旧版，仍受支持）。
src/config/upstreams.yaml 定义上游LLM提供程序（URL、密钥、健康检查）。
src/config/tools.yaml 网关管理工具的注册表。
src/config/security.yaml API密钥、ACL、工具/模块允许/拒绝列表。
docs/ 包含指南、参考和系统文档。看 docs/README.md 用于导航。
docs/guides/OperatorRunbook.md 第2天操作、超控、故障排除。

环境变量： GATEWAY_AGENT_CONFIG, GATEWAY_UPSTREAM_CONFIG, GATEWAY_SECURITY_CONFIG, GATEWAY_AGENT_DISCOVERY_PATH, GATEWAY_AGENT_AUTO_RELOAD, GATEWAY_AGENT_WATCH （要求 watchfiles)等等。

🧰 故障排除

问题 解决
代理人未列入 /v1/models 检查 /admin/agents/errors 对于发现失败，请运行 scripts/install_agent_deps.py，确保模块导出 agent.
403禁止使用 /security/preview 检查决定，申请 /security/override 或更新 security.yaml.
流媒体提前结束 确认 stream:true；检查日志 sdk_agent.failure.
工具调用被拒绝 工具不在列表中；更新 src/config/security.yaml 和POST /security/refresh.
监视模式处于非活动状态 安装 watchfiles (pip install "agent-gateway[watch]")并设置 GATEWAY_AGENT_WATCH=1.
利率上限（429） 增加 rate_limit.per_minute 或旋转API键。

看 docs/guides/Troubleshooting.md 以便进行更深入的调试。

🧱 制定目标

目标 描述
make run 使用reload启动FastAPI应用程序。
make fmt / make lint 通过Ruff进行格式化和lint编码。
make test / make coverage 运行pytest并生成覆盖率报告。
make test-acceptance 执行入站验收套件（固定装置+API检查）。
python scripts/install_agent_deps.py 安装由插入代理声明的依赖项。
make smoke 执行端到端烟雾测试。
make docker-build 构建容器映像。
make sbom 生成CycloneDX SBOM

🌐 API表面

端点 描述
POST /v1/chat/completions OpenAI兼容的聊天完成（支持SSE）。
GET /v1/models 列出ACL筛选的模型。
/agents, /upstreams, /tools 注册表刷新的管理端点。
/security/refresh 重新加载并验证API密钥。
/metrics, /metrics/prometheus 度量JSON和Prometheus导出器。
/health 轻质活性探针。

所有管理端点都需要 x-api-key未经授权或速率受限的请求返回 403 或 429.

🔍 可观察性和安全性

  • 日志： 具有请求ID和工具调用跟踪的结构化JSON。
  • 韵律学： /metrics 和 /metrics/prometheus 性能数据的端点； /admin/metrics 包括工具故障和故障计数下降。
  • 安全： API密钥、ACL、速率限制、审核脚本和夜间验证。原生SDK工具需要在中进行显式分配 src/config/security.yaml (local_tools_allowlist)除非您使用网关管理工具。
  • 看 docs/systems/observability.md 获取详细的日志记录/指标/错误指导。

🧪 测试和包装

  • 满的 pytest 覆盖注册中心、适配器、工具和API路由。
  • 中的规范SDK示例 tests/fixtures/dropin_agents.
  • Dockerfile 和 docker-compose.yaml 用于可重复构建。
  • 发布管道包括签名映像、SBOM和变更日志更新。

🗺️ 路线图

在当前的差距/计划报告中跟踪发展里程碑 docs/ReviewsAndReports/.遗产 AgentGateway_10-Step_Development_Plan.md 退休了。

🧠 代理示例

这些示例代表了可用于初始实验的三个级别的代理复杂性。

皮质
多种药剂的混合物		 突触
适量混合药剂		 火花
一种轻质混合药剂

相关 MCP