AG-UI Dojo 應用程式提供了一個互動式環境，用於測試和探索實作 AG-UI 通訊協定的 Microsoft Agent Framework 代理程式。 Dojo 提供了一個可視化界面來連接到您的代理並與所有 7 個 AG-UI 功能進行交互。
先決條件
在開始之前，請確保您擁有：
- Python 3.10 或更高版本
- 用於依賴管理的 uv
- OpenAI API 金鑰或 Azure OpenAI 端點
- Node.js 和 pnpm（用於運行 Dojo 前端）
安裝
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 Agent Framework （Python）]]
開始探索範例代理程式
可用的範例代理程式
整合範例透過不同的代理程式端點示範所有 7 個 AG-UI 功能：
| 端點 | 特徵 / 功能 | Description |
|---|---|---|
/agentic_chat |
功能 1：代理聊天 | 具有工具呼叫的基本對話代理程式 |
/backend_tool_rendering |
功能二：後端工具渲染 | 具有自訂工具 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. 在道場中測試
- 啟動您的伺服器
- 在
http://localhost:3000啟動 Dojo - 將伺服器 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
故障排除
伺服器連線問題
如果 Dojo 無法連接至您的伺服器：
- 驗證伺服器是否在正確的埠上執行（預設值：8888）
- 請檢查 Dojo 中的伺服器 URL 是否符合您的伺服器位址
- 確保沒有防火牆阻止連接
- 在瀏覽器主控台中尋找 CORS 錯誤
代理未出現
如果您的客服專員未出現在 Dojo 下拉式清單中：
- 確認代理程式端點已正確註冊
- 檢查伺服器日誌是否有任何啟動錯誤
- 確保
add_agent_framework_fastapi_endpoint通話成功完成
環境變數問題
如果您看到驗證錯誤：
- 確認您的
.env檔案位於正確的目錄中 - 檢查是否已設定所有必要的環境變數
- 確保 API 金鑰和端點有效
- 更改環境變數後重新啟動伺服器
後續步驟
其他資源
即將推出。