DevUI for Microsoft Agent Framework

1.0.0b260409 · active · verified Wed Apr 15

agent-framework-devui is a lightweight, standalone sample application providing a debug UI for the Microsoft Agent Framework. It offers an OpenAI-compatible API server for running and testing AI agents and workflows, supporting directory-based discovery, in-memory entity registration, and a gallery of sample entities. It also includes an OpenAI Proxy feature, enabling direct testing of OpenAI models via the interface while keeping API keys secure on the server. Primarily designed as an 'inner-loop' developer tool, it visualizes agent execution, including reasoning, actions, and observations.

Common errors

```
ModuleNotFoundError: No module named 'agent_framework'
```
cause The 'agent_framework' package is not installed in the current Python environment.

fix Install the package using pip: 'pip install agent-framework'.
```
ImportError: cannot import name 'DevServer' from 'agent_framework.devui'
```
cause The 'DevServer' class is not available in the 'agent_framework.devui' module, possibly due to version incompatibility or incorrect import.

fix Ensure you are using the correct version of 'agent-framework-devui' and check the module's documentation for the correct import statement.
```
AttributeError: module 'agent_framework' has no attribute 'serve'
```
cause The 'serve' function is not defined in the 'agent_framework' module, possibly due to incorrect usage or version mismatch.

fix Verify the module's documentation for the correct usage of the 'serve' function and ensure compatibility with your version.
```
TypeError: serve() got an unexpected keyword argument 'entities_dir'
```
cause The 'serve' function does not accept 'entities_dir' as a keyword argument, indicating a possible API change or incorrect usage.

fix Review the function's signature in the module's documentation and update your code accordingly.
```
ValueError: No entities found in the specified directory
```
cause The specified directory does not contain any valid agents or workflows for discovery.

fix Ensure the directory structure follows the required format with '__init__.py' files exporting 'agent' or 'workflow' variables as per the documentation.

Warnings

breaking The Microsoft Agent Framework, including DevUI, is currently in a development/preview stage. APIs and features are subject to frequent changes, and building from source is sometimes recommended over pre-release packages to ensure the latest updates.
Fix: Refer to the official GitHub repository (microsoft/agent-framework) for the latest API changes and consider installing directly from source for the most up-to-date features, or pin to a specific pre-release version.
gotcha DevUI is explicitly stated as a 'sample app' and 'not intended for production use.' Its primary purpose is for local development, testing, and debugging of agents and workflows within the Agent Framework, rather than deployment.
Fix: For production environments or advanced features, it is recommended to build a custom interface and API server using the core Agent Framework SDK.
gotcha When using DevUI's OpenAI Proxy feature or agents that interact with OpenAI-compatible clients (like `OpenAIChatClient`), an `OPENAI_API_KEY` (or a `GITHUB_TOKEN` for GitHub Models) must be configured as an environment variable on the backend for proper authentication.
Fix: Set `OPENAI_API_KEY` (or `GITHUB_TOKEN`) as an environment variable in your development environment before launching DevUI or the agent application.
gotcha A specific architectural consideration for developers is to avoid using `async with` context managers when creating agents with Model Context Protocol (MCP) tools for DevUI.
Fix: When integrating MCP tools with agents intended for DevUI, ensure that `async with` is not used in their definition or interaction logic.
gotcha Due to its pre-release status, installation of `agent-framework-devui` typically requires the `--pre` flag with pip (e.g., `pip install agent-framework-devui --pre`) to access the latest beta versions.
Fix: Always include the `--pre` flag during `pip install` to ensure the package is found and installed correctly. Omission may result in 'No matching distribution found' errors.

Install

pip install agent-framework-devui --pre Install pre-release version

Imports

serve
```
from agent_framework.devui import serve
```
Main function to launch the DevUI.
Agent
```
from agent_framework import Agent
```
Class for defining AI agents within the framework.
OpenAIChatClient
```
from agent_framework.openai import OpenAIChatClient
```
Client for connecting agents to OpenAI-compatible chat models.

Quickstart

This quickstart demonstrates how to define a simple agent with a tool and then launch the DevUI to interact with it. The `serve` function starts the web UI and API server, making the agent accessible for testing and debugging in a browser. Ensure `OPENAI_API_KEY` is set as an environment variable if you intend for the agent to use an actual OpenAI client.

import os
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient
from agent_framework.devui import serve

# NOTE: Set OPENAI_API_KEY environment variable for actual API calls
# Example for a simple tool
def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"Weather in {location}: 72°F and sunny"

# Create your agent
agent = Agent(
    name="WeatherAgent",
    client=OpenAIChatClient(api_key=os.environ.get('OPENAI_API_KEY', '')) if os.environ.get('OPENAI_API_KEY') else None, # Pass API key if available
    tools=[get_weather]
)

# Launch debug UI - this opens a browser to http://localhost:8080
print("Launching DevUI... access at http://localhost:8080")
serve(entities=[agent], auto_open=True)

view raw JSON →