Add databricks-agents framework for building discoverable agents

dbx-agent-app/.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install mkdocs-material mkdocstrings[python] pymdown-extensions
+
+    - name: Build and deploy
+      run: |
+        mkdocs gh-deploy --force

dbx-agent-app/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: |
+        python -m build
+
+    - name: Check package
+      run: |
+        twine check dist/*
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: |
+        twine upload dist/*

dbx-agent-app/.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Lint with ruff
+      run: |
+        ruff check src/
+
+    - name: Check formatting with black
+      run: |
+        black --check src/
+
+    - name: Type check with mypy (informational)
+      continue-on-error: true
+      run: |
+        pip install mypy types-httpx
+        mypy src/ --ignore-missing-imports
+
+    - name: Run tests with pytest
+      run: |
+        pytest tests/ -v --cov=dbx_agent_app --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      if: matrix.python-version == '3.11'
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false

dbx-agent-app/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.hypothesis/
+
+# Documentation
+docs/_build/
+site/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.env
+.env.local

dbx-agent-app/CLAUDE.md

@@ -0,0 +1,105 @@
+# dbx-agent-app
+
+## Project Overview
+
+Agent platform for Databricks Apps. Package name: `dbx-agent-app` (PyPI), import as `dbx_agent_app` (Python).
+
+Build agents with any framework (official Databricks SDK, LangGraph, CrewAI, plain FastAPI). Deploy the platform to discover, test, trace, and govern all of them.
+
+## Architecture: Agent Platform (v0.3)
+
+This is NOT an agent-building SDK. It's the **control plane** for agents in your workspace.
+
+### What the platform does:
+- **Auto-discovery** — scans workspace apps for agent cards at `/.well-known/agent.json`
+- **Testing** — call any agent via `/invocations` (Databricks standard protocol)
+- **Governance** — register discovered agents in Unity Catalog, track lineage
+- **Observability** — trace timing, protocol detection, agent handoff routing
+- **Multi-agent deploy** — `agents.yaml` → topological sort → deploy → wire → permissions
+
+### What agent developers do:
+- Build agents with any framework
+- Use `@app_agent` decorator (recommended) or `add_agent_card()` helper
+- Deploy as Databricks Apps
+
+## Primary API: `@app_agent` decorator
+
+The recommended way to build agents. One decorator gives you `/invocations`, agent card, health, and MCP.
+
+```python
+from dbx_agent_app import app_agent, AgentRequest, AgentResponse
+
+@app_agent(name="my_agent", description="Does stuff", capabilities=["search"])
+async def my_agent(request: AgentRequest) -> AgentResponse:
+    return AgentResponse.text(f"You said: {request.last_user_message}")
+
+# my_agent.app → FastAPI with /invocations, /.well-known/agent.json, /health
+# uvicorn app:my_agent.app
+```
+
+Return types auto-coerced: `AgentResponse`, `str`, or `dict`.
+
+### Wire protocol types
+
+SDK types that replace `mlflow.types.responses` — no mlflow dependency needed:
+
+- `AgentRequest(input=[InputItem(role="user", content="...")])` — `.messages`, `.last_user_message`
+- `AgentResponse.text("Hello!")` / `AgentResponse.from_dict({...})` — `.to_wire()`
+- `StreamEvent.text_delta("chunk")` / `StreamEvent.done("full text")` — `.to_sse()`
+
+### LangChain compatibility
+
+For agents using LangChain, replace `self.prep_msgs_for_llm()` with:
+
+```python
+from dbx_agent_app.core.compat import to_langchain_messages
+messages = to_langchain_messages(request)  # -> List[BaseMessage]
+```
+
+## Helpers API (plain FastAPI)
+
+For agents that want full control over their FastAPI app:
+
+```python
+from fastapi import FastAPI
+from dbx_agent_app import add_agent_card, add_mcp_endpoints
+
+app = FastAPI()
+
+@app.post("/invocations")
+async def invocations(request): ...
+
+add_agent_card(app, name="my_agent", description="...", capabilities=["search"])
+add_mcp_endpoints(app, tools=[...])  # optional
+```
+
+## Project Structure
+
+- `src/dbx_agent_app/core/` — `@app_agent` decorator, wire types, helpers, compat
+- `src/dbx_agent_app/dashboard/` — **the platform app** (FastAPI + React SPA)
+- `src/dbx_agent_app/deploy/` — multi-agent deploy orchestration (agents.yaml)
+- `src/dbx_agent_app/discovery/` — workspace agent scanning
+- `src/dbx_agent_app/registry/` — Unity Catalog registration
+- `src/dbx_agent_app/mcp/` — MCP JSON-RPC server
+- `src/dbx_agent_app/cli.py` — CLI entry point
+- `examples/` — example agents using helpers + official framework
+- `tests/` — SDK tests
+
+## Key Conventions
+
+- SDK dependencies stay minimal (FastAPI, uvicorn, pydantic, httpx, databricks-sdk)
+- mlflow is optional (`pip install dbx-agent-app[mlflow]`)
+- The dashboard is the primary product, not a side feature
+- `agents.yaml` defines agent systems (topology, dependencies, wiring)
+- Examples use `@app_agent` decorator (preferred) or plain FastAPI + `add_agent_card()`
+- Platform is framework-agnostic: any app serving `/.well-known/agent.json` gets discovered
+
+## CLI Commands
+
+```
+dbx-agent-app deploy     # Deploy agents from agents.yaml
+dbx-agent-app status     # Show deployment status
+dbx-agent-app destroy    # Tear down deployed agents
+dbx-agent-app dashboard  # Launch platform locally (dev)
+dbx-agent-app platform   # Deploy platform as a Databricks App
+```

dbx-agent-app/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to dbx-agent-app
+
+Thank you for your interest in contributing to dbx-agent-app! This project is a Databricks Labs initiative to make it easier to build discoverable AI agents on Databricks Apps.
+
+## Development Setup
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+3. Run tests:
+   ```bash
+   pytest
+   ```
+
+## Code Style
+
+- Use Black for code formatting: `black src/`
+- Use Ruff for linting: `ruff check src/`
+- Line length: 100 characters (configured in `pyproject.toml`)
+- Type hints are encouraged for public APIs
+
+## Testing
+
+- Write tests for new features using pytest
+- Place tests in the `tests/` directory
+- Run tests with: `pytest tests/`
+- Aim for >80% code coverage
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Add tests for new functionality
+5. Run tests and linting: `pytest && black src/ && ruff check src/`
+6. Commit with a clear message describing the change
+7. Push and create a pull request
+
+## PR Guidelines
+
+- **Clear description**: Explain what the PR does and why
+- **Tests included**: All new features should have tests
+- **Documentation updated**: Update README.md and docstrings as needed
+- **Small, focused changes**: One feature or fix per PR
+- **Passes CI**: All tests and linting must pass
+
+## Areas for Contribution
+
+We welcome contributions in these areas:
+
+- **Unity Catalog integration**: Register agents as UC catalog objects
+- **MCP server support**: Add Model Context Protocol server capabilities
+- **Orchestration patterns**: Multi-agent coordination utilities
+- **RAG utilities**: Built-in vector search and retrieval patterns
+- **Observability**: Logging, metrics, and tracing integrations
+- **Documentation**: Examples, guides, and API documentation
+- **Testing**: Improve test coverage and test utilities
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Start a discussion for design questions
+- Check existing issues and PRs before starting work
+
+## Code of Conduct
+
+Be respectful, inclusive, and constructive in all interactions. This is a professional community focused on building great tools together.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.