Add databricks-agents framework for building discoverable agents

databricks-agents/.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

databricks-agents/.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/*

databricks-agents/.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=databricks_agents --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

databricks-agents/.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

databricks-agents/CLAUDE.md

@@ -0,0 +1,83 @@
+# databricks-agent-deploy
+
+## Project Overview
+
+Agent platform for Databricks Apps. Package name: `databricks-agent-deploy` (PyPI), import as `databricks_agents` (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
+- Add `add_agent_card(app, ...)` for discoverability (optional, ~1 line)
+- Deploy as Databricks Apps
+
+## Primary API (helpers for agent developers)
+
+```python
+from fastapi import FastAPI
+from databricks_agents import add_agent_card, add_mcp_endpoints
+
+app = FastAPI()
+
+@app.post("/invocations")
+async def invocations(request): ...
+
+# Make discoverable by the platform (~1 line)
+add_agent_card(app, name="my_agent", description="...", capabilities=["search"])
+
+# Optional: expose tools via MCP
+add_mcp_endpoints(app, tools=[...])
+```
+
+## Legacy AgentApp (backward compatible)
+
+`AgentApp` still works but is no longer the primary pattern. Prefer plain FastAPI + helpers.
+
+```python
+agent = AgentApp(name="my_agent", description="...", capabilities=["..."])
+@agent.tool(description="Search")
+async def search(query: str) -> dict: ...
+app = agent.as_fastapi()
+```
+
+## Project Structure
+
+- `src/databricks_agents/core/` — helpers (`add_agent_card`, `add_mcp_endpoints`) + legacy AgentApp
+- `src/databricks_agents/dashboard/` — **the platform app** (FastAPI + React SPA)
+- `src/databricks_agents/deploy/` — multi-agent deploy orchestration (agents.yaml)
+- `src/databricks_agents/discovery/` — workspace agent scanning
+- `src/databricks_agents/registry/` — Unity Catalog registration
+- `src/databricks_agents/mcp/` — MCP JSON-RPC server (decoupled from AgentApp)
+- `src/databricks_agents/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 databricks-agent-deploy[mlflow]`)
+- The dashboard is the primary product, not a side feature
+- `agents.yaml` defines agent systems (topology, dependencies, wiring)
+- Examples use plain FastAPI + `add_agent_card()`, NOT AgentApp
+- Platform is framework-agnostic: any app serving `/.well-known/agent.json` gets discovered
+
+## CLI Commands
+
+```
+databricks-agents deploy     # Deploy agents from agents.yaml
+databricks-agents status     # Show deployment status
+databricks-agents destroy    # Tear down deployed agents
+databricks-agents dashboard  # Launch platform locally (dev)
+databricks-agents platform   # Deploy platform as a Databricks App
+```

databricks-agents/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to databricks-agents
+
+Thank you for your interest in contributing to databricks-agents! 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.