AG-UI Dojo 应用程序提供了一个交互式环境，用于测试和探索实现 AG-UI 协议的 Microsoft Agent Framework 代理。 Dojo 提供了一个可视界面，用于连接到代理并与所有 7 个 AG-UI 功能进行交互。
先决条件
在开始之前，请确保具备：
- Python 3.10 或更高版本
- uv 用于依赖项管理
- OpenAI API 密钥或 Azure OpenAI 终结点
- Node.js 和 pnpm （用于运行 Dojo 前端）
Installation
1.克隆 AG-UI 存储库
首先，克隆包含 Dojo 应用程序和 Microsoft Agent Framework 集成示例的 AG-UI 存储库：
git clone https://github.com/ag-oss/ag-ui.git
cd ag-ui
2.导航到示例目录
cd integrations/microsoft-agent-framework/python/examples
3.安装 Python 依赖项
使用 uv 来安装所需的依赖项。
uv sync
4. 配置环境变量
.env从提供的模板创建文件：
cp .env.example .env
请编辑.env文件并添加您的API认证信息。
# For OpenAI
OPENAI_API_KEY=your_api_key_here
OPENAI_CHAT_MODEL_ID="gpt-4.1"
# Or for Azure OpenAI
AZURE_OPENAI_ENDPOINT=your_endpoint_here
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=your_deployment_here
注释
如果使用DefaultAzureCredential代替api_key进行身份验证，请确保您已通过 Azure（例如，通过az login）进行认证。 有关详细信息，请参阅 Azure 标识文档。
运行 Dojo 应用程序
1.启动后端服务器
在示例目录中，使用示例代理启动后端服务器：
cd integrations/microsoft-agent-framework/python/examples
uv run dev
默认情况下，服务器将启动 http://localhost:8888 。
2. 启动 Dojo 前端
打开新的终端窗口，导航到 AG-UI 存储库的根目录，然后导航到 Dojo 应用程序目录：
cd apps/dojo
pnpm install
pnpm dev
Dojo 前端将在 http://localhost:3000.
3.连接到代理
在浏览器中打开
http://localhost:3000将服务器 URL 配置为
http://localhost:8888从下拉列表中选择“Microsoft代理框架（Python）
开始探索示例代理
可用示例代理
集成示例通过不同的代理终结点演示所有 7 个 AG-UI 功能：
| 端点 | 功能 / 特点 | Description |
|---|---|---|
/agentic_chat |
功能 1：代理聊天 | 使用工具调用的基本聊天代理 |
/backend_tool_rendering |
功能 2：后台工具渲染 | 使用自定义工具 UI 呈现的代理 |
/human_in_the_loop |
功能 3：人类参与 | 具有审批工作流的代理 |
/agentic_generative_ui |
功能 4：自主生成 UI | 将任务分解为步骤并提供流式更新的代理 |
/tool_based_generative_ui |
功能 5：基于工具的生成 UI | 生成自定义 UI 组件的代理 |
/shared_state |
功能 6：共享状态 | 具有双向状态同步的代理 |
/predictive_state_updates |
功能 7：预测状态更新 | 工具执行期间具有预测状态更新的代理 |
测试自己的代理
若要使用 Dojo 测试自己的代理，请执行以下操作：
1.创建代理
按照 入门 指南创建新的代理：
from agent_framework import Agent
from agent_framework_azure_ai import AzureOpenAIChatClient
# Create your agent
chat_client = AzureOpenAIChatClient(
endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
deployment_name=os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"),
)
agent = Agent(
name="my_test_agent",
chat_client=chat_client,
system_message="You are a helpful assistant.",
)
2.将代理添加到服务器
在 FastAPI 应用程序中，注册代理终结点：
from fastapi import FastAPI
from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
import uvicorn
app = FastAPI()
# Register your agent
add_agent_framework_fastapi_endpoint(
app=app,
path="/my_agent",
agent=agent,
)
if __name__ == "__main__":
uvicorn.run(app, host="127.0.0.1", port=8888)
3. 在 Dojo 中进行测试
- 启动服务器
- 打开 Dojo 在
http://localhost:3000 - 将服务器 URL 设置为
http://localhost:8888 - 代理将在终结点下拉列表中显示为“my_agent”
- 选择它并开始测试
项目结构
AG-UI 存储库的集成示例遵循以下结构：
integrations/microsoft-agent-framework/python/examples/
├── agents/
│ ├── agentic_chat/ # Feature 1: Basic chat agent
│ ├── backend_tool_rendering/ # Feature 2: Backend tool rendering
│ ├── human_in_the_loop/ # Feature 3: Human-in-the-loop
│ ├── agentic_generative_ui/ # Feature 4: Streaming state updates
│ ├── tool_based_generative_ui/ # Feature 5: Custom UI components
│ ├── shared_state/ # Feature 6: Bidirectional state sync
│ ├── predictive_state_updates/ # Feature 7: Predictive state updates
│ └── dojo.py # FastAPI application setup
├── pyproject.toml # Dependencies and scripts
├── .env.example # Environment variable template
└── README.md # Integration examples documentation
Troubleshooting
服务器连接问题
如果 Dojo 无法连接到你的服务器：
- 验证服务器是否在正确的端口上运行（默认值：8888）
- 检查 Dojo 中的服务器 URL 是否与服务器地址匹配
- 确保没有防火墙阻止连接
- 在浏览器控制台中查找 CORS 错误
代理未显示
如果代理未显示在 Dojo 下拉列表中：
- 验证代理终结点是否已正确注册
- 检查服务器日志中是否存在任何启动错误
- 确保
add_agent_framework_fastapi_endpoint呼叫已成功完成
环境变量问题
如果看到身份验证错误：
-
.env验证文件是否位于正确的目录中 - 检查是否已设置所有必需的环境变量
- 确保 API 密钥和终结点有效
- 更改环境变量后重启服务器
后续步骤
其他资源
即将推出。