Agent Gateway

代理网关

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

______________________________________________________________________

📚 目录

• 亮点

• 快速开始

- Linux/macOS - 视窗

• 插入式代理工作流

• 配置和文件

• 故障排除

• 制定目标

• API表面

• 可观察性和安全性

• 测试和包装

• 路线图

• 代理示例

______________________________________________________________________

🚀 亮点

______________________________________________________________________

⚡ 快速开始

Linux/macOS

git clone https://github.com//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//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//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])

1. 运行网关

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

1. 列出型号

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

1. 与客服聊天

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

1. 可选： 使用 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 用于惯例、固定装置和故障排除。

______________________________________________________________________

⚙️ 配置和文件

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

______________________________________________________________________

🧰 故障排除

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

______________________________________________________________________

🧱 制定目标

______________________________________________________________________

🌐 API表面

所有管理端点都需要 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 退休了。

______________________________________________________________________

🧠 代理示例

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

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

______________________________________________________________________