microsoft--agent-framework/python/samples/02-agents/devui

DevUI Samples

This folder contains sample agents and workflows designed to work with the Agent Framework DevUI - a lightweight web interface for running and testing agents interactively.

What is DevUI?

DevUI is a sample application that provides:

• A web interface for testing agents and workflows
• OpenAI-compatible API endpoints
• Directory-based entity discovery
• In-memory entity registration
• Sample entity gallery

Note

: DevUI is a sample app for development and testing. For production use, build your own custom interface using the Agent Framework SDK.

Quick Start

Option 1: In-Memory Mode (Programmatic Registration)

Run a single sample directly. This demonstrates how to register agents and workflows in code without using DevUI's directory discovery.

This sample uses Microsoft Foundry. Before running it:

1. Copy .env.example in this folder to .env, or export the same values in your shell
2. Set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_MODEL
3. Run az login

Then start the sample:

cd python/samples/02-agents/devui
python in_memory_mode.py

This opens your browser at http://localhost:8090 with two Foundry-backed agents and a simple text transformation workflow.

Option 2: Directory Discovery with Shared Root .env

Run the folder-level launcher to load samples/02-agents/devui/.env and then start DevUI with directory discovery for this folder:

cd python/samples/02-agents/devui
python main.py

This starts the server at http://localhost:8080 with all discoverable agents and workflows available. The root .env acts as shared fallback configuration for discovered samples.

Option 3: Directory Discovery with the devui CLI

If you prefer the CLI directly, you can still launch DevUI from this folder:

cd python/samples/02-agents/devui
devui .

DevUI discovery checks for a sample-specific .env first and then falls back to .env in samples/02-agents/devui/.

Sample Structure

DevUI discovers samples from Python packages that export either agent or workflow.

Typical agent layout:

agent_name/
├── __init__.py      # Must export: agent = ...
├── agent.py         # Agent implementation
└── .env.example     # Optional example environment variables

Typical workflow layout:

workflow_name/
├── __init__.py      # Must export: workflow = ...
├── workflow.py      # Workflow implementation
├── workflow.yaml    # Optional declarative definition
└── .env.example     # Optional example environment variables

Available Samples

Agents

Sample	What it demonstrates	Required keys / auth
agent_weather/	A richer Foundry-backed weather agent that shows chat middleware, function middleware, tool calling, and an approval-required tool alongside auto-approved tools.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, plus Azure CLI auth via az login
agent_foundry/	A minimal Foundry-backed weather agent with current weather and forecast tools. Use this when you want the smallest possible directory-discovered agent sample.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, plus Azure CLI auth via az login
agent_content_understanding/	Upload and analyze documents, images, audio, and video with Azure Content Understanding.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, AZURE_CONTENTUNDERSTANDING_ENDPOINT, plus Azure CLI auth via az login
agent_content_understanding_file_search_azure_openai/	Combine Azure Content Understanding extraction with Azure OpenAI vector-store file search.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, AZURE_CONTENTUNDERSTANDING_ENDPOINT, plus Azure CLI auth via az login
agent_content_understanding_file_search_foundry/	Combine Azure Content Understanding extraction with Foundry vector-store file search.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, AZURE_CONTENTUNDERSTANDING_ENDPOINT, plus Azure CLI auth via az login

Workflows

Sample	What it demonstrates	Required keys / auth
workflow_declarative/	A YAML-defined workflow loaded through WorkflowFactory, with nested age-based branching and no model client code.	None
workflow_with_agents/	A content review workflow that uses agents as executors and routes based on structured review output (Writer -> Reviewer -> Editor/Publisher -> Summarizer).	AZURE_OPENAI_ENDPOINT, plus AZURE_OPENAI_CHAT_MODEL or AZURE_OPENAI_MODEL; Azure CLI auth via az login; AZURE_OPENAI_API_VERSION is optional
workflow_spam/	A multi-step spam detection workflow with human-in-the-loop approval, branching for spam vs. legitimate messages, and a final reporting step.	None
workflow_fanout/	A larger fan-out/fan-in data processing workflow with parallel validation, multiple transformations, QA, aggregation, and demo failure toggles.	None

Standalone Examples

Sample	What it demonstrates	Required keys / auth
in_memory_mode.py	Registers multiple entities directly in Python: two Foundry-backed agents plus a simple workflow, all served from one file without directory discovery.	FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, plus Azure CLI auth via az login

Environment Variables

For samples that require external services:

1. Copy .env.example to .env
2. Fill in the required values
3. Run az login for samples that use Azure CLI authentication

Directory discovery checks .env files in this order:

1. The entity directory itself, for example agent_weather/.env
2. The root DevUI samples folder, samples/02-agents/devui/.env

That means the root .env.example can hold shared defaults for multiple samples, while a sample-specific .env can override those values when needed.

in_memory_mode.py and main.py both load .env from samples/02-agents/devui/, so the root .env.example in this folder is the right starting point for both commands.

Alternatively, set environment variables globally:

# Foundry-backed samples
export FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com"
export FOUNDRY_MODEL="gpt-4o"

# Azure OpenAI workflow_with_agents sample
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_CHAT_MODEL="gpt-4o"
export AZURE_OPENAI_MODEL="gpt-4o"

az login

Using DevUI with Your Own Agents

To make your agent discoverable by DevUI:

1. Create a folder for your agent
2. Add an __init__.py that exports agent or workflow
3. (Optional) Add a .env file for environment variables

Example:

# my_agent/__init__.py
from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    name="MyAgent",
    description="My custom agent",
    client=OpenAIChatClient(),
    # ... your configuration
)

Then run:

devui /path/to/my/agents/folder

API Usage

DevUI exposes OpenAI-compatible endpoints:

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent-framework",
    "input": "What is the weather in Seattle?",
    "extra_body": {"entity_id": "agent_directory_weather-agent_<uuid>"}
  }'

List available entities:

curl http://localhost:8080/v1/entities

Learn More

• DevUI Documentation
• Agent Framework Documentation
• Sample Guidelines

Troubleshooting

Missing credentials or settings: Check your .env files, confirm the required variables for the sample you are running, and make sure az login has completed for Azure-authenticated samples.

Import errors: Make sure you've installed the devui package:

pip install agent-framework-devui --pre

Port conflicts: DevUI uses ports 8080 (directory mode) and 8090 (in-memory mode) by default. Close other services or specify a different port:

devui --port 8888