agent-framework-devui 0.0.1a0__tar.gz → 1.0.0b251001__tar.gz

agent_framework_devui-1.0.0b251001/.gitignore

@@ -0,0 +1,19 @@
+# Test artifacts
+tests/captured_messages/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Local development files
+.env
+*.log
+
+# IDE files
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db

agent_framework_devui-1.0.0b251001/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

agent_framework_devui-1.0.0b251001/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: agent-framework-devui
+Version: 1.0.0b251001
+Summary: Debug UI for Microsoft Agent Framework with OpenAI-compatible API server.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pytest>=7.0.0 ; extra == "all"
+Requires-Dist: watchdog>=3.0.0 ; extra == "all"
+Requires-Dist: pytest>=7.0.0 ; extra == "dev"
+Requires-Dist: watchdog>=3.0.0 ; extra == "dev"
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+Provides-Extra: all
+Provides-Extra: dev
+
+# DevUI - A Sample App for Running Agents and Workflows
+
+A lightweight, standalone sample app interface for running entities (agents/workflows) in the Microsoft Agent Framework supporting **directory-based discovery**, **in-memory entity registration**, and **sample entity gallery**.
+
+> [!IMPORTANT]
+> DevUI is a **sample app** to help you get started with the Agent Framework. It is **not** intended for production use. For production, or for features beyond what is provided in this sample app, it is recommended that you build your own custom interface and API server using the Agent Framework SDK.
+
+![DevUI Screenshot](./docs/devuiscreen.png)
+
+## Quick Start
+
+```bash
+# Install
+pip install agent-framework-devui
+```
+
+You can also launch it programmatically
+
+```python
+from agent_framework import ChatAgent
+from agent_framework.openai import OpenAIChatClient
+from agent_framework.devui import serve
+
+def get_weather(location: str) -> str:
+    """Get weather for a location."""
+    return f"Weather in {location}: 72°F and sunny"
+
+# Create your agent
+agent = ChatAgent(
+    name="WeatherAgent",
+    chat_client=OpenAIChatClient(),
+    tools=[get_weather]
+)
+
+# Launch debug UI - that's it!
+serve(entities=[agent], auto_open=True)
+# → Opens browser to http://localhost:8080
+```
+
+In addition, if you have agents/workflows defined in a specific directory structure (see below), you can launch DevUI from the _cli_ to discover and run them.
+
+```bash
+
+# Launch web UI + API server
+devui ./agents --port 8080
+# → Web UI: http://localhost:8080
+# → API: http://localhost:8080/v1/*
+```
+
+When DevUI starts with no discovered entities, it displays a **sample entity gallery** with curated examples from the Agent Framework repository to help you get started quickly.
+
+## Directory Structure
+
+For your agents to be discovered by the DevUI, they must be organized in a directory structure like below. Each agent/workflow must have an `__init__.py` that exports the required variable (`agent` or `workflow`).
+
+**Note**: `.env` files are optional but will be automatically loaded if present in the agent/workflow directory or parent entities directory. Use them to store API keys, configuration variables, and other environment-specific settings.
+
+```
+agents/
+├── weather_agent/
+│   ├── __init__.py      # Must export: agent = ChatAgent(...)
+│   ├── agent.py
+│   └── .env             # Optional: API keys, config vars
+├── my_workflow/
+│   ├── __init__.py      # Must export: workflow = WorkflowBuilder()...
+│   ├── workflow.py
+│   └── .env             # Optional: environment variables
+└── .env                 # Optional: shared environment variables
+```
+
+## Viewing Telemetry (Otel Traces) in DevUI
+
+Agent Framework emits OpenTelemetry (Otel) traces for various operations. You can view these traces in DevUI by enabling tracing when starting the server.
+
+```bash
+devui ./agents --tracing framework
+```
+
+## OpenAI-Compatible API
+
+For convenience, you can interact with the agents/workflows using the standard OpenAI API format. Just specify the `entity_id` in the `extra_body` field. This can be an `agent_id` or `workflow_id`.
+
+```bash
+# Standard OpenAI format
+curl -X POST http://localhost:8080/v1/responses \
+  -H "Content-Type: application/json" \
+  -d @- << 'EOF'
+{
+  "model": "agent-framework",
+  "input": "Hello world",
+  "extra_body": {"entity_id": "weather_agent"}
+}
+
+```
+
+## CLI Options
+
+```bash
+devui [directory] [options]
+
+Options:
+  --port, -p      Port (default: 8080)
+  --host          Host (default: 127.0.0.1)
+  --headless      API only, no UI
+  --config        YAML config file
+  --tracing       none|framework|workflow|all
+  --reload        Enable auto-reload
+```
+
+## Key Endpoints
+
+- `GET /v1/entities` - List discovered agents/workflows
+- `GET /v1/entities/{entity_id}/info` - Get detailed entity information
+- `POST /v1/entities/add` - Add entity from URL (for gallery samples)
+- `DELETE /v1/entities/{entity_id}` - Remove remote entity
+- `POST /v1/responses` - Execute agent/workflow (streaming or sync)
+- `GET /health` - Health check
+- `POST /v1/threads` - Create thread for agent (optional)
+- `GET /v1/threads?agent_id={id}` - List threads for agent
+- `GET /v1/threads/{thread_id}` - Get thread info
+- `DELETE /v1/threads/{thread_id}` - Delete thread
+- `GET /v1/threads/{thread_id}/messages` - Get thread messages
+
+## Implementation
+
+- **Discovery**: `agent_framework_devui/_discovery.py`
+- **Execution**: `agent_framework_devui/_executor.py`
+- **Message Mapping**: `agent_framework_devui/_mapper.py`
+- **Session Management**: `agent_framework_devui/_session.py`
+- **API Server**: `agent_framework_devui/_server.py`
+- **CLI**: `agent_framework_devui/_cli.py`
+
+## Examples
+
+See `samples/` for working agent and workflow implementations.
+
+## License
+
+MIT
+

agent_framework_devui-1.0.0b251001/README.md

@@ -0,0 +1,139 @@
+# DevUI - A Sample App for Running Agents and Workflows
+
+A lightweight, standalone sample app interface for running entities (agents/workflows) in the Microsoft Agent Framework supporting **directory-based discovery**, **in-memory entity registration**, and **sample entity gallery**.
+
+> [!IMPORTANT]
+> DevUI is a **sample app** to help you get started with the Agent Framework. It is **not** intended for production use. For production, or for features beyond what is provided in this sample app, it is recommended that you build your own custom interface and API server using the Agent Framework SDK.
+
+![DevUI Screenshot](./docs/devuiscreen.png)
+
+## Quick Start
+
+```bash
+# Install
+pip install agent-framework-devui
+```
+
+You can also launch it programmatically
+
+```python
+from agent_framework import ChatAgent
+from agent_framework.openai import OpenAIChatClient
+from agent_framework.devui import serve
+
+def get_weather(location: str) -> str:
+    """Get weather for a location."""
+    return f"Weather in {location}: 72°F and sunny"
+
+# Create your agent
+agent = ChatAgent(
+    name="WeatherAgent",
+    chat_client=OpenAIChatClient(),
+    tools=[get_weather]
+)
+
+# Launch debug UI - that's it!
+serve(entities=[agent], auto_open=True)
+# → Opens browser to http://localhost:8080
+```
+
+In addition, if you have agents/workflows defined in a specific directory structure (see below), you can launch DevUI from the _cli_ to discover and run them.
+
+```bash
+
+# Launch web UI + API server
+devui ./agents --port 8080
+# → Web UI: http://localhost:8080
+# → API: http://localhost:8080/v1/*
+```
+
+When DevUI starts with no discovered entities, it displays a **sample entity gallery** with curated examples from the Agent Framework repository to help you get started quickly.
+
+## Directory Structure
+
+For your agents to be discovered by the DevUI, they must be organized in a directory structure like below. Each agent/workflow must have an `__init__.py` that exports the required variable (`agent` or `workflow`).
+
+**Note**: `.env` files are optional but will be automatically loaded if present in the agent/workflow directory or parent entities directory. Use them to store API keys, configuration variables, and other environment-specific settings.
+
+```
+agents/
+├── weather_agent/
+│   ├── __init__.py      # Must export: agent = ChatAgent(...)
+│   ├── agent.py
+│   └── .env             # Optional: API keys, config vars
+├── my_workflow/
+│   ├── __init__.py      # Must export: workflow = WorkflowBuilder()...
+│   ├── workflow.py
+│   └── .env             # Optional: environment variables
+└── .env                 # Optional: shared environment variables
+```
+
+## Viewing Telemetry (Otel Traces) in DevUI
+
+Agent Framework emits OpenTelemetry (Otel) traces for various operations. You can view these traces in DevUI by enabling tracing when starting the server.
+
+```bash
+devui ./agents --tracing framework
+```
+
+## OpenAI-Compatible API
+
+For convenience, you can interact with the agents/workflows using the standard OpenAI API format. Just specify the `entity_id` in the `extra_body` field. This can be an `agent_id` or `workflow_id`.
+
+```bash
+# Standard OpenAI format
+curl -X POST http://localhost:8080/v1/responses \
+  -H "Content-Type: application/json" \
+  -d @- << 'EOF'
+{
+  "model": "agent-framework",
+  "input": "Hello world",
+  "extra_body": {"entity_id": "weather_agent"}
+}
+
+```
+
+## CLI Options
+
+```bash
+devui [directory] [options]
+
+Options:
+  --port, -p      Port (default: 8080)
+  --host          Host (default: 127.0.0.1)
+  --headless      API only, no UI
+  --config        YAML config file
+  --tracing       none|framework|workflow|all
+  --reload        Enable auto-reload
+```
+
+## Key Endpoints
+
+- `GET /v1/entities` - List discovered agents/workflows
+- `GET /v1/entities/{entity_id}/info` - Get detailed entity information
+- `POST /v1/entities/add` - Add entity from URL (for gallery samples)
+- `DELETE /v1/entities/{entity_id}` - Remove remote entity
+- `POST /v1/responses` - Execute agent/workflow (streaming or sync)
+- `GET /health` - Health check
+- `POST /v1/threads` - Create thread for agent (optional)
+- `GET /v1/threads?agent_id={id}` - List threads for agent
+- `GET /v1/threads/{thread_id}` - Get thread info
+- `DELETE /v1/threads/{thread_id}` - Delete thread
+- `GET /v1/threads/{thread_id}/messages` - Get thread messages
+
+## Implementation
+
+- **Discovery**: `agent_framework_devui/_discovery.py`
+- **Execution**: `agent_framework_devui/_executor.py`
+- **Message Mapping**: `agent_framework_devui/_mapper.py`
+- **Session Management**: `agent_framework_devui/_session.py`
+- **API Server**: `agent_framework_devui/_server.py`
+- **CLI**: `agent_framework_devui/_cli.py`
+
+## Examples
+
+See `samples/` for working agent and workflow implementations.
+
+## License
+
+MIT

agent_framework_devui-1.0.0b251001/agent_framework_devui/__init__.py

@@ -0,0 +1,151 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent Framework DevUI - Debug interface with OpenAI compatible API server."""
+
+import importlib.metadata
+import logging
+import webbrowser
+from typing import Any
+
+from ._server import DevServer
+from .models import AgentFrameworkRequest, OpenAIError, OpenAIResponse, ResponseStreamEvent
+from .models._discovery_models import DiscoveryResponse, EntityInfo, EnvVarRequirement
+
+logger = logging.getLogger(__name__)
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+
+def serve(
+    entities: list[Any] | None = None,
+    entities_dir: str | None = None,
+    port: int = 8080,
+    host: str = "127.0.0.1",
+    auto_open: bool = False,
+    cors_origins: list[str] | None = None,
+    ui_enabled: bool = True,
+    tracing_enabled: bool = False,
+) -> None:
+    """Launch Agent Framework DevUI with simple API.
+
+    Args:
+        entities: List of entities for in-memory registration (IDs auto-generated)
+        entities_dir: Directory to scan for entities
+        port: Port to run server on
+        host: Host to bind server to
+        auto_open: Whether to automatically open browser
+        cors_origins: List of allowed CORS origins
+        ui_enabled: Whether to enable the UI
+        tracing_enabled: Whether to enable OpenTelemetry tracing
+    """
+    import re
+
+    import uvicorn
+
+    # Validate host parameter early for security
+    if not re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0|[a-zA-Z0-9.-]+)$", host):
+        raise ValueError(f"Invalid host: {host}. Must be localhost, IP address, or valid hostname")
+
+    # Validate port parameter
+    if not isinstance(port, int) or not (1 <= port <= 65535):
+        raise ValueError(f"Invalid port: {port}. Must be integer between 1 and 65535")
+
+    # Configure tracing environment variables if enabled
+    if tracing_enabled:
+        import os
+
+        # Only set if not already configured by user
+        if not os.environ.get("ENABLE_OTEL"):
+            os.environ["ENABLE_OTEL"] = "true"
+            logger.info("Set ENABLE_OTEL=true for tracing")
+
+        if not os.environ.get("ENABLE_SENSITIVE_DATA"):
+            os.environ["ENABLE_SENSITIVE_DATA"] = "true"
+            logger.info("Set ENABLE_SENSITIVE_DATA=true for tracing")
+
+        if not os.environ.get("OTLP_ENDPOINT"):
+            os.environ["OTLP_ENDPOINT"] = "http://localhost:4317"
+            logger.info("Set OTLP_ENDPOINT=http://localhost:4317 for tracing")
+
+    # Create server with direct parameters
+    server = DevServer(
+        entities_dir=entities_dir, port=port, host=host, cors_origins=cors_origins, ui_enabled=ui_enabled
+    )
+
+    # Register in-memory entities if provided
+    if entities:
+        logger.info(f"Registering {len(entities)} in-memory entities")
+        # Store entities for later registration during server startup
+        server._pending_entities = entities
+
+    app = server.get_app()
+
+    if auto_open:
+
+        def open_browser() -> None:
+            import http.client
+            import re
+            import time
+
+            # Validate host and port for security
+            if not re.match(r"^(localhost|127\.0\.0\.1|0\.0\.0\.0|[a-zA-Z0-9.-]+)$", host):
+                logger.warning(f"Invalid host for auto-open: {host}")
+                return
+
+            if not isinstance(port, int) or not (1 <= port <= 65535):
+                logger.warning(f"Invalid port for auto-open: {port}")
+                return
+
+            # Wait for server to be ready by checking health endpoint
+            browser_url = f"http://{host}:{port}"
+
+            for _ in range(30):  # 15 second timeout (30 * 0.5s)
+                try:
+                    # Use http.client for safe connection handling (standard library)
+                    conn = http.client.HTTPConnection(host, port, timeout=1)
+                    try:
+                        conn.request("GET", "/health")
+                        response = conn.getresponse()
+                        if response.status == 200:
+                            webbrowser.open(browser_url)
+                            return
+                    finally:
+                        conn.close()
+                except (http.client.HTTPException, OSError, TimeoutError):
+                    pass
+                time.sleep(0.5)
+
+            # Fallback: open browser anyway after timeout
+            webbrowser.open(browser_url)
+
+        import threading
+
+        threading.Thread(target=open_browser, daemon=True).start()
+
+    logger.info(f"Starting Agent Framework DevUI on {host}:{port}")
+    uvicorn.run(app, host=host, port=port, log_level="info")
+
+
+def main() -> None:
+    """CLI entry point for devui command."""
+    from ._cli import main as cli_main
+
+    cli_main()
+
+
+# Export main public API
+__all__ = [
+    "AgentFrameworkRequest",
+    "DevServer",
+    "DiscoveryResponse",
+    "EntityInfo",
+    "EnvVarRequirement",
+    "OpenAIError",
+    "OpenAIResponse",
+    "ResponseStreamEvent",
+    "main",
+    "serve",
+]

agent_framework_devui-1.0.0b251001/agent_framework_devui/_cli.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Command line interface for Agent Framework DevUI."""
+
+import argparse
+import logging
+import os
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure logging for the server."""
+    log_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    logging.basicConfig(level=getattr(logging, level.upper()), format=log_format, datefmt="%Y-%m-%d %H:%M:%S")
+
+
+def create_cli_parser() -> argparse.ArgumentParser:
+    """Create the command line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="devui",
+        description="Launch Agent Framework DevUI - Debug interface with OpenAI compatible API",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  devui                             # Scan current directory
+  devui ./agents                    # Scan specific directory
+  devui --port 8000                 # Custom port
+  devui --headless                  # API only, no UI
+  devui --tracing                   # Enable OpenTelemetry tracing
+        """,
+    )
+
+    parser.add_argument(
+        "directory", nargs="?", default=".", help="Directory to scan for entities (default: current directory)"
+    )
+
+    parser.add_argument("--port", "-p", type=int, default=8080, help="Port to run server on (default: 8080)")
+
+    parser.add_argument("--host", default="127.0.0.1", help="Host to bind server to (default: 127.0.0.1)")
+
+    parser.add_argument("--no-open", action="store_true", help="Don't automatically open browser")
+
+    parser.add_argument("--headless", action="store_true", help="Run without UI (API only)")
+
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Logging level (default: INFO)",
+    )
+
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload for development")
+
+    parser.add_argument("--tracing", action="store_true", help="Enable OpenTelemetry tracing for Agent Framework")
+
+    parser.add_argument("--version", action="version", version=f"Agent Framework DevUI {get_version()}")
+
+    return parser
+
+
+def get_version() -> str:
+    """Get the package version."""
+    try:
+        from . import __version__
+
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def validate_directory(directory: str) -> str:
+    """Validate and normalize the entities directory."""
+    if not directory:
+        directory = "."
+
+    abs_dir = os.path.abspath(directory)
+
+    if not os.path.exists(abs_dir):
+        print(f"❌ Error: Directory '{directory}' does not exist", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+    if not os.path.isdir(abs_dir):
+        print(f"❌ Error: '{directory}' is not a directory", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+    return abs_dir
+
+
+def print_startup_info(entities_dir: str, host: str, port: int, ui_enabled: bool, reload: bool) -> None:
+    """Print startup information."""
+    print("🤖 Agent Framework DevUI")  # noqa: T201
+    print("=" * 50)  # noqa: T201
+    print(f"📁 Entities directory: {entities_dir}")  # noqa: T201
+    print(f"🌐 Server URL: http://{host}:{port}")  # noqa: T201
+    print(f"🎨 UI enabled: {'Yes' if ui_enabled else 'No'}")  # noqa: T201
+    print(f"🔄 Auto-reload: {'Yes' if reload else 'No'}")  # noqa: T201
+    print("=" * 50)  # noqa: T201
+    print("🔍 Scanning for entities...")  # noqa: T201
+
+
+def main() -> None:
+    """Main CLI entry point."""
+    parser = create_cli_parser()
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(args.log_level)
+
+    # Validate directory
+    entities_dir = validate_directory(args.directory)
+
+    # Extract parameters directly from args
+    ui_enabled = not args.headless
+
+    # Print startup info
+    print_startup_info(entities_dir, args.host, args.port, ui_enabled, args.reload)
+
+    # Import and start server
+    try:
+        from . import serve
+
+        serve(
+            entities_dir=entities_dir,
+            port=args.port,
+            host=args.host,
+            auto_open=not args.no_open,
+            ui_enabled=ui_enabled,
+            tracing_enabled=args.tracing,
+        )
+
+    except KeyboardInterrupt:
+        print("\n👋 Shutting down Agent Framework DevUI...")  # noqa: T201
+        sys.exit(0)
+    except Exception as e:
+        logger.exception("Failed to start server")
+        print(f"❌ Error: {e}", file=sys.stderr)  # noqa: T201
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()