Skip to content

Commit 5e8a7ae

Browse files
moonbox3victordibia
moonbox3
and
victordibia
authored
Python: DevUI Python draft docs (#796)
* DevUI Python draft docs * Improvements * Fix author * Really fix author * Update image * Fix Improve DevUI documentation to match current implementation - Fix --tracing flag (boolean, not level-based) - Remove non-existent --config CLI option - Add missing --no-open and --auth-token options - Fix ChatAgent parameter: system_prompt → instructions - Clarify that DevUI captures Agent Framework traces (doesn't create spans) - Add /meta endpoint and OTLP_ENDPOINT documentation - Correct UI modes section (what's restricted vs available) - Expand authentication docs with env var and CLI examples * Adjust image code --------- Co-authored-by: Victor Dibia <victor.dibia@gmail.com>
1 parent 375a24f commit 5e8a7ae

9 files changed

Lines changed: 963 additions & 0 deletions

File tree

‎agent-framework/TOC.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ items:
1818
href: user-guide/workflows/TOC.yml
1919
- name: Hosting
2020
href: user-guide/hosting/TOC.yml
21+
- name: DevUI
22+
href: user-guide/devui/TOC.yml
2123
- name: Integrations
2224
items:
2325
- name: AG-UI

‎agent-framework/user-guide/devui/TOC.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
- name: Overview
2+
href: index.md
3+
- name: Directory Discovery
4+
href: directory-discovery.md
5+
- name: API Reference
6+
href: api-reference.md
7+
- name: Tracing & Observability
8+
href: tracing.md
9+
- name: Security & Deployment
10+
href: security.md
11+
- name: Samples
12+
href: samples.md

‎agent-framework/user-guide/devui/api-reference.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: DevUI API Reference
3+
description: Learn about the OpenAI-compatible API endpoints provided by DevUI.
4+
author: moonbox3
5+
ms.topic: reference
6+
ms.author: evmattso
7+
ms.date: 12/10/2025
8+
ms.service: agent-framework
9+
zone_pivot_groups: programming-languages
10+
---
11+
12+
# API Reference
13+
14+
DevUI provides an OpenAI-compatible Responses API, allowing you to use the OpenAI SDK or any HTTP client to interact with your agents and workflows.
15+
16+
::: zone pivot="programming-language-csharp"
17+
18+
## Coming Soon
19+
20+
DevUI documentation for C# is coming soon. Please check back later or refer to the Python documentation for conceptual guidance.
21+
22+
::: zone-end
23+
24+
::: zone pivot="programming-language-python"
25+
26+
## Base URL
27+
28+
```
29+
http://localhost:8080/v1
30+
```
31+
32+
The port can be configured with the `--port` CLI option.
33+
34+
## Authentication
35+
36+
By default, DevUI does not require authentication for local development. When running with `--auth`, Bearer token authentication is required.
37+
38+
## Using the OpenAI SDK
39+
40+
### Basic Request
41+
42+
```python
43+
from openai import OpenAI
44+
45+
client = OpenAI(
46+
base_url="http://localhost:8080/v1",
47+
api_key="not-needed" # API key not required for local DevUI
48+
)
49+
50+
response = client.responses.create(
51+
metadata={"entity_id": "weather_agent"}, # Your agent/workflow name
52+
input="What's the weather in Seattle?"
53+
)
54+
55+
# Extract text from response
56+
print(response.output[0].content[0].text)
57+
```
58+
59+
### Streaming
60+
61+
```python
62+
response = client.responses.create(
63+
metadata={"entity_id": "weather_agent"},
64+
input="What's the weather in Seattle?",
65+
stream=True
66+
)
67+
68+
for event in response:
69+
# Process streaming events
70+
print(event)
71+
```
72+
73+
### Multi-turn Conversations
74+
75+
Use the standard OpenAI `conversation` parameter for multi-turn conversations:
76+
77+
```python
78+
# Create a conversation
79+
conversation = client.conversations.create(
80+
metadata={"agent_id": "weather_agent"}
81+
)
82+
83+
# First turn
84+
response1 = client.responses.create(
85+
metadata={"entity_id": "weather_agent"},
86+
input="What's the weather in Seattle?",
87+
conversation=conversation.id
88+
)
89+
90+
# Follow-up turn (continues the conversation)
91+
response2 = client.responses.create(
92+
metadata={"entity_id": "weather_agent"},
93+
input="How about tomorrow?",
94+
conversation=conversation.id
95+
)
96+
```
97+
98+
DevUI automatically retrieves the conversation's message history and passes it to the agent.
99+
100+
## REST API Endpoints
101+
102+
### Responses API (OpenAI Standard)
103+
104+
Execute an agent or workflow:
105+
106+
```bash
107+
curl -X POST http://localhost:8080/v1/responses \
108+
-H "Content-Type: application/json" \
109+
-d '{
110+
"metadata": {"entity_id": "weather_agent"},
111+
"input": "What is the weather in Seattle?"
112+
}'
113+
```
114+
115+
### Conversations API (OpenAI Standard)
116+
117+
| Endpoint | Method | Description |
118+
|----------|--------|-------------|
119+
| `/v1/conversations` | POST | Create a conversation |
120+
| `/v1/conversations/{id}` | GET | Get conversation details |
121+
| `/v1/conversations/{id}` | POST | Update conversation metadata |
122+
| `/v1/conversations/{id}` | DELETE | Delete a conversation |
123+
| `/v1/conversations?agent_id={id}` | GET | List conversations (DevUI extension) |
124+
| `/v1/conversations/{id}/items` | POST | Add items to conversation |
125+
| `/v1/conversations/{id}/items` | GET | List conversation items |
126+
| `/v1/conversations/{id}/items/{item_id}` | GET | Get a conversation item |
127+
128+
### Entity Management (DevUI Extension)
129+
130+
| Endpoint | Method | Description |
131+
|----------|--------|-------------|
132+
| `/v1/entities` | GET | List discovered agents/workflows |
133+
| `/v1/entities/{entity_id}/info` | GET | Get detailed entity information |
134+
| `/v1/entities/{entity_id}/reload` | POST | Hot reload entity (developer mode) |
135+
136+
### Health Check
137+
138+
```bash
139+
curl http://localhost:8080/health
140+
```
141+
142+
### Server Metadata
143+
144+
Get server configuration and capabilities:
145+
146+
```bash
147+
curl http://localhost:8080/meta
148+
```
149+
150+
Returns:
151+
- `ui_mode` - Current mode (`developer` or `user`)
152+
- `version` - DevUI version
153+
- `framework` - Framework name (`agent_framework`)
154+
- `runtime` - Backend runtime (`python`)
155+
- `capabilities` - Feature flags (tracing, OpenAI proxy, deployment)
156+
- `auth_required` - Whether authentication is enabled
157+
158+
## Event Mapping
159+
160+
DevUI maps Agent Framework events to OpenAI Responses API events. The table below shows the mapping:
161+
162+
### Lifecycle Events
163+
164+
| OpenAI Event | Agent Framework Event |
165+
|--------------|----------------------|
166+
| `response.created` + `response.in_progress` | `AgentStartedEvent` |
167+
| `response.completed` | `AgentCompletedEvent` |
168+
| `response.failed` | `AgentFailedEvent` |
169+
| `response.created` + `response.in_progress` | `WorkflowStartedEvent` |
170+
| `response.completed` | `WorkflowCompletedEvent` |
171+
| `response.failed` | `WorkflowFailedEvent` |
172+
173+
### Content Types
174+
175+
| OpenAI Event | Agent Framework Content |
176+
|--------------|------------------------|
177+
| `response.content_part.added` + `response.output_text.delta` | `TextContent` |
178+
| `response.reasoning_text.delta` | `TextReasoningContent` |
179+
| `response.output_item.added` | `FunctionCallContent` (initial) |
180+
| `response.function_call_arguments.delta` | `FunctionCallContent` (args) |
181+
| `response.function_result.complete` | `FunctionResultContent` |
182+
| `response.output_item.added` (image) | `DataContent` (images) |
183+
| `response.output_item.added` (file) | `DataContent` (files) |
184+
| `error` | `ErrorContent` |
185+
186+
### Workflow Events
187+
188+
| OpenAI Event | Agent Framework Event |
189+
|--------------|----------------------|
190+
| `response.output_item.added` (ExecutorActionItem) | `ExecutorInvokedEvent` |
191+
| `response.output_item.done` (ExecutorActionItem) | `ExecutorCompletedEvent` |
192+
| `response.output_item.added` (ResponseOutputMessage) | `WorkflowOutputEvent` |
193+
194+
### DevUI Custom Extensions
195+
196+
DevUI adds custom event types for Agent Framework-specific functionality:
197+
198+
- `response.function_approval.requested` - Function approval requests
199+
- `response.function_approval.responded` - Function approval responses
200+
- `response.function_result.complete` - Server-side function execution results
201+
- `response.workflow_event.complete` - Workflow events
202+
- `response.trace.complete` - Execution traces
203+
204+
These custom extensions are namespaced and can be safely ignored by standard OpenAI clients.
205+
206+
## OpenAI Proxy Mode
207+
208+
DevUI provides an **OpenAI Proxy** feature for testing OpenAI models directly through the interface without creating custom agents. Enable via Settings in the UI.
209+
210+
```bash
211+
curl -X POST http://localhost:8080/v1/responses \
212+
-H "X-Proxy-Backend: openai" \
213+
-d '{"model": "gpt-4.1-mini", "input": "Hello"}'
214+
```
215+
216+
> [!NOTE]
217+
> Proxy mode requires `OPENAI_API_KEY` environment variable configured on the backend.
218+
219+
::: zone-end
220+
221+
## Next Steps
222+
223+
- [Tracing & Observability](./tracing.md) - View traces for debugging
224+
- [Security & Deployment](./security.md) - Secure your DevUI deployment

‎agent-framework/user-guide/devui/directory-discovery.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
title: DevUI Directory Discovery
3+
description: Learn how to structure your agents and workflows for automatic discovery by DevUI.
4+
author: moonbox3
5+
ms.topic: how-to
6+
ms.author: evmattso
7+
ms.date: 12/10/2025
8+
ms.service: agent-framework
9+
zone_pivot_groups: programming-languages
10+
---
11+
12+
# Directory Discovery
13+
14+
DevUI can automatically discover agents and workflows from a directory structure. This enables you to organize multiple entities and launch them all with a single command.
15+
16+
::: zone pivot="programming-language-csharp"
17+
18+
## Coming Soon
19+
20+
DevUI documentation for C# is coming soon. Please check back later or refer to the Python documentation for conceptual guidance.
21+
22+
::: zone-end
23+
24+
::: zone pivot="programming-language-python"
25+
26+
## Directory Structure
27+
28+
For your agents and workflows to be discovered by DevUI, they must be organized in a specific directory structure. Each entity must have an `__init__.py` file that exports the required variable (`agent` or `workflow`).
29+
30+
```
31+
entities/
32+
weather_agent/
33+
__init__.py # Must export: agent = ChatAgent(...)
34+
agent.py # Agent implementation (optional, can be in __init__.py)
35+
.env # Optional: API keys, config vars
36+
my_workflow/
37+
__init__.py # Must export: workflow = WorkflowBuilder()...
38+
workflow.py # Workflow implementation (optional)
39+
.env # Optional: environment variables
40+
.env # Optional: shared environment variables
41+
```
42+
43+
## Agent Example
44+
45+
Create a directory for your agent with the required `__init__.py`:
46+
47+
**`weather_agent/__init__.py`**:
48+
49+
```python
50+
from agent_framework import ChatAgent
51+
from agent_framework.openai import OpenAIChatClient
52+
53+
def get_weather(location: str) -> str:
54+
"""Get weather for a location."""
55+
return f"Weather in {location}: 72F and sunny"
56+
57+
agent = ChatAgent(
58+
name="weather_agent",
59+
chat_client=OpenAIChatClient(),
60+
tools=[get_weather],
61+
instructions="You are a helpful weather assistant."
62+
)
63+
```
64+
65+
The key requirement is that the `__init__.py` file must export a variable named `agent` (for agents) or `workflow` (for workflows).
66+
67+
## Workflow Example
68+
69+
**`my_workflow/__init__.py`**:
70+
71+
```python
72+
from agent_framework.workflows import WorkflowBuilder
73+
74+
workflow = (
75+
WorkflowBuilder()
76+
.add_executor(...)
77+
.add_edge(...)
78+
.build()
79+
)
80+
```
81+
82+
## Environment Variables
83+
84+
DevUI automatically loads `.env` files if present:
85+
86+
1. **Entity-level `.env`**: Placed in the agent/workflow directory, loaded only for that entity
87+
2. **Parent-level `.env`**: Placed in the entities root directory, loaded for all entities
88+
89+
Example `.env` file:
90+
91+
```bash
92+
OPENAI_API_KEY=sk-...
93+
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
94+
```
95+
96+
> [!TIP]
97+
> Create a `.env.example` file to document required environment variables without exposing actual values. Never commit `.env` files with real credentials to source control.
98+
99+
## Launching with Directory Discovery
100+
101+
Once your directory structure is set up, launch DevUI:
102+
103+
```bash
104+
# Discover all entities in ./entities directory
105+
devui ./entities
106+
107+
# With custom port
108+
devui ./entities --port 9000
109+
110+
# With auto-reload for development
111+
devui ./entities --reload
112+
```
113+
114+
## Sample Gallery
115+
116+
When DevUI starts with no discovered entities, it displays a **sample gallery** with curated examples from the Agent Framework repository. You can:
117+
118+
- Browse available sample agents and workflows
119+
- Download samples to review and customize
120+
- Run samples locally to get started quickly
121+
122+
## Troubleshooting
123+
124+
### Entity not discovered
125+
126+
- Ensure the `__init__.py` file exports `agent` or `workflow` variable
127+
- Check for syntax errors in your Python files
128+
- Verify the directory is directly under the path passed to `devui`
129+
130+
### Environment variables not loaded
131+
132+
- Ensure the `.env` file is in the correct location
133+
- Check file permissions
134+
- Use `--reload` flag to pick up changes during development
135+
136+
::: zone-end
137+
138+
## Next Steps
139+
140+
- [API Reference](./api-reference.md) - Learn about the OpenAI-compatible API
141+
- [Tracing & Observability](./tracing.md) - Debug your agents with traces

0 commit comments

Comments
 (0)