DevUI 设计为 用于本地开发的示例应用程序。 如果需要在 localhost 之外公开 DevUI，本页介绍安全注意事项和最佳做法。
警告
DevUI 不适用于生产用途。 对于生产部署，请使用具有适当安全措施的 Agent Framework SDK 生成自己的自定义接口。
即将推出
即将推出适用于 C# 的 DevUI 文档。 请稍后查看或参阅 Python 文档了解概念指南。
UI 模式
DevUI 提供两种控制对功能的访问的模式：
开发人员模式（默认）
对所有功能的完全访问权限：
- 包含跟踪信息的调试面板
- 用于快速开发的热重载 （
/v1/entities/{id}/reload） - 部署工具 （
/v1/deployments） - 用于调试的冗长错误消息
devui ./agents # Developer mode is the default
用户模式
简化的受限接口：
- 聊天界面和聊天管理
- 实体列表和基本信息
- 开发者 API 被禁用（热重载、部署）
- 通用错误消息（详细记录服务器端）
devui ./agents --mode user
Authentication
使用 --auth 标志启用持有者令牌身份验证：
devui ./agents --auth
启用身份验证后：
- 对于 localhost：令牌是自动生成并在控制台中显示的
- 对于 网络公开 的部署：必须通过
DEVUI_AUTH_TOKEN环境变量或--auth-token标志提供令牌
# Auto-generated token (localhost only)
devui ./agents --auth
# Custom token via CLI
devui ./agents --auth --auth-token "your-secure-token"
# Custom token via environment variable
export DEVUI_AUTH_TOKEN="your-secure-token"
devui ./agents --auth --host 0.0.0.0
所有 API 请求都必须在标头中包含 Authorization 有效的持有者令牌：
curl http://localhost:8080/v1/entities \
-H "Authorization: Bearer your-token-here"
建议的部署配置
如果需要向最终用户公开 DevUI（不建议用于生产）：
devui ./agents --mode user --auth --host 0.0.0.0
此配置：
- 限制面向开发人员的 API
- 要求身份验证
- 绑定到所有网络接口
安全功能
DevUI 包括多个安全措施：
| 功能 / 特点 | Description |
|---|---|
| Localhost 绑定 | 默认情况下绑定到 127.0.0.1 |
| 用户模式 | 限制开发者API |
| 持有者身份验证 | 基于令牌的可选身份验证 |
| 本地实体加载 | 仅从本地目录或内存中加载实体 |
| 无远程执行 | 没有远程代码执行功能 |
最佳做法
凭据管理
- 在文件中存储 API 密钥和机密
.env - 从不将
.env文件提交到源代码管理 - 使用
.env.example文件记录所需的变量
# .env.example (safe to commit)
OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# .env (never commit)
OPENAI_API_KEY=sk-actual-key
AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com/
网络安全
- 使 DevUI 绑定到 localhost 进行开发
- 如果需要外部访问，请使用反向代理（nginx、Caddy）
- 通过反向代理启用 HTTPS
- 在代理级别实现适当的身份验证
实体安全性
- 在运行之前检查所有代理/工作流代码
- 仅从受信任的源加载实体
- 谨慎使用具有副作用的工具（文件访问、网络调用）
资源清理
注册清理挂钩，以在关闭时正确关闭凭据和资源：
from azure.identity.aio import DefaultAzureCredential
from agent_framework import Agent
from agent_framework.azure import AzureOpenAIChatClient
from agent_framework_devui import register_cleanup, serve
credential = DefaultAzureCredential()
client = AzureOpenAIChatClient()
agent = Agent(name="MyAgent", chat_client=client)
# Register cleanup hook - credential will be closed on shutdown
register_cleanup(agent, credential.close)
serve(entities=[agent])
MCP 工具注意事项
将 MCP（模型上下文协议）工具与 DevUI 配合使用时：
# Correct - DevUI handles cleanup automatically
mcp_tool = MCPStreamableHTTPTool(url="http://localhost:8011/mcp", chat_client=chat_client)
agent = Agent(tools=mcp_tool)
serve(entities=[agent])
重要
使用用于 DevUI 的 MCP 工具创建代理时，请勿使用 async with 上下文管理器。 在执行之前，连接将关闭。 MCP 工具使用延迟初始化，并在首次使用时自动连接。