diff --git a/Cargo.lock b/Cargo.lock
index ed781e66..806162aa 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -180,6 +180,7 @@ dependencies = [
  "reqwest 0.13.1",
  "serde",
  "serde_json",
+ "serde_yaml",
  "similar",
  "tempfile",
  "tera",
@@ -236,6 +237,7 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_with",
+ "serde_yaml",
  "sha2",
  "sqlx",
  "swc_atoms",
@@ -5067,6 +5069,7 @@ version = "8.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5bcdef0be6fe7f6fa333b1073c949729274b05f123a0ad7efcb8efd878e5c3b1"
 dependencies = [
+ "globset",
  "sha2",
  "walkdir",
 ]
diff --git a/Cargo.toml b/Cargo.toml
index 1bd49829..1b9c65f1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -70,7 +70,7 @@ hex = "0.4"
 rand = "0.8.5"
 walkdir = "2.5.0"
 url = "2.5.8"
-rust-embed = "8"
+rust-embed = { version = "8", features = ["include-exclude"] }
 zip = "2.2"
 flate2 = "1.1"
 sha2 = "0.10"
diff --git a/README.md b/README.md
index bdadc0ee..f7ed3498 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,58 @@
 
 💡 The main idea of `apx` is to provide convenient, fast and AI-friendly development experience.
 
+## Agents
+
+`apx init --addon agent` adds a complete agent framework — tool-calling loop, composition patterns, OBO auth, MCP, and dev UI.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  /_apx/agent (dev UI)          POST /invocations            │
+│       │                              │                      │
+│       └──────────┐  ┌────────────────┘                      │
+│                  ▼  ▼                                       │
+│            ┌───────────┐     ┌──────────────┐               │
+│            │ LlmAgent  │────▶│ FMAPI (LLM)  │               │
+│            └─────┬─────┘     └──────────────┘               │
+│                  │ tool calls                               │
+│       ┌──────────┼──────────┐                               │
+│       ▼          ▼          ▼                               │
+│  ┌─────────┐ ┌────────┐ ┌───────────┐                      │
+│  │ Local   │ │ Genie  │ │ Sub-agent │                      │
+│  │ tools   │ │ Space  │ │ /invoke   │                      │
+│  └────┬────┘ └────┬───┘ └─────┬─────┘                      │
+│       │           │           │                             │
+│       └───────────┴───────────┘                             │
+│            OBO auth (X-Forwarded-Access-Token)              │
+│            forwarded through every call                     │
+└─────────────────────────────────────────────────────────────┘
+         │                    │
+    /mcp/sse              /.well-known/agent.json
+    (MCP server)          (A2A discovery)
+```
+
+**What you get out of the box:**
+
+| Feature | How |
+|---|---|
+| OBO auth in every tool | `ws: Dependencies.UserClient` — token flows automatically |
+| MCP server | `/mcp/sse` — connect Claude Desktop, Cursor, etc. |
+| A2A discovery | `/.well-known/agent.json` — auto-populated at request time |
+| Agent composition | `SequentialAgent`, `ParallelAgent`, `LoopAgent`, `RouterAgent`, `HandoffAgent` |
+| Dev UI | `/_apx/agent` — chat, tool trace, MCP URL copy |
+| Deploy | `apx deploy` — one command to production |
+| MLflow eval | `app_predict_fn(url)` → `mlflow.genai.evaluate()` |
+
+**Define tools as plain functions — type hints become the schema:**
+
+```python
+def query_genie(question: str, space_id: str, ws: Dependencies.Workspace) -> str:
+    """Answer a question using a Genie Space."""
+    return ws.genie.ask(space_id=space_id, question=question).answer or ""
+
+agent = Agent(tools=[query_genie])
+```
+
 ## 🚀 Quickstart
 
 Install `apx`:
diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
index 12a06263..6d5912d0 100644
--- a/crates/cli/Cargo.toml
+++ b/crates/cli/Cargo.toml
@@ -31,6 +31,7 @@ tokio.workspace = true
 tracing.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+serde_yaml.workspace = true
 chrono.workspace = true
 reqwest.workspace = true
 toml.workspace = true
diff --git a/crates/cli/src/build.rs b/crates/cli/src/build.rs
index 0aa21a81..f08502da 100644
--- a/crates/cli/src/build.rs
+++ b/crates/cli/src/build.rs
@@ -8,8 +8,10 @@ use crate::common::find_app_dir;
 use crate::run_cli_async_helper;
 use apx_core::api_generator::generate_openapi;
 use apx_core::common::{
-    ensure_dir, format_elapsed_ms, run_command_streaming_with_output, run_preflight_checks, spinner,
+    ensure_dir, format_elapsed_ms, read_project_metadata, run_command_streaming_with_output,
+    run_preflight_checks, spinner,
 };
+use apx_core::dotenv::DotenvFile;
 use apx_core::external::uv::Uv;
 
 const DEFAULT_BUILD_DIR: &str = ".build";
@@ -40,39 +42,46 @@ pub async fn run(args: BuildArgs) -> i32 {
 async fn run_inner(args: BuildArgs) -> Result<(), String> {
     let app_path = find_app_dir(args.app_path)?;
     let build_dir = app_path.join(&args.build_path);
-
     println!("Building project in {}", app_path.display());
+    run_build(&app_path, &build_dir).await?;
+    println!("Build completed");
+    Ok(())
+}
 
+/// Core build logic shared with `apx deploy`.
+pub async fn run_build(app_path: &Path, build_dir: &Path) -> Result<(), String> {
     // Run preflight checks: generate _metadata.py, __dist__, uv sync, version file, bun install if needed
     debug!("Running preflight checks before build");
-    let _preflight = run_preflight_checks(&app_path).await?;
+    let _preflight = run_preflight_checks(app_path).await?;
 
     // Set up build directory
     if build_dir.exists() {
-        fs::remove_dir_all(&build_dir)
+        fs::remove_dir_all(build_dir)
             .map_err(|err| format!("Failed to remove build directory: {err}"))?;
     }
-    ensure_dir(&build_dir)?;
+    ensure_dir(build_dir)?;
     fs::write(build_dir.join(".gitignore"), "*\n")
         .map_err(|err| format!("Failed to write build .gitignore: {err}"))?;
 
-    generate_openapi(&app_path).await?;
-
-    if args.skip_ui_build {
-        println!("Skipping UI build");
-    } else {
-        build_ui(&app_path).await?;
+    generate_openapi(app_path).await?;
+    let meta = read_project_metadata(app_path)?;
+    if meta.has_ui() {
+        build_ui(app_path).await?;
     }
 
-    build_wheel(&app_path, &args.build_path).await?;
-    copy_app_config_files(&app_path, &build_dir)?;
+    // build_path is relative to app_path; find_wheel_file needs the resolved build_dir
+    let build_path = build_dir
+        .strip_prefix(app_path)
+        .map(|p| p.to_path_buf())
+        .unwrap_or_else(|_| build_dir.to_path_buf());
+    build_wheel(app_path, &build_path).await?;
+    copy_app_config_files(app_path, build_dir)?;
 
-    let wheel_file = find_wheel_file(&build_dir)?;
+    let wheel_file = find_wheel_file(build_dir)?;
     let requirements_path = build_dir.join("requirements.txt");
     fs::write(&requirements_path, format!("{wheel_file}\n"))
         .map_err(|err| format!("Failed to write requirements.txt: {err}"))?;
 
-    println!("Build completed");
     Ok(())
 }
 
@@ -91,6 +100,16 @@ async fn build_wheel(app_path: &Path, build_path: &Path) -> Result<(), String> {
     let mut cmd = uv.build_wheel_command(app_path, build_path).into_command();
     cmd.env("UV_DYNAMIC_VERSIONING_BYPASS", build_version);
 
+    // Forward UV_* vars from the project .env so users can set e.g. UV_OFFLINE=1
+    // or UV_NATIVE_TLS=1 once in .env rather than prefixing every command.
+    if let Ok(dotenv) = DotenvFile::read(&app_path.join(".env")) {
+        for (key, value) in dotenv.get_vars() {
+            if key.starts_with("UV_") {
+                cmd.env(&key, &value);
+            }
+        }
+    }
+
     let result =
         run_command_streaming_with_output(cmd, &sp, "🐍 Wheel:", "Failed to build Python wheel")
             .await;
diff --git a/crates/cli/src/deploy.rs b/crates/cli/src/deploy.rs
new file mode 100644
index 00000000..8d7abec4
--- /dev/null
+++ b/crates/cli/src/deploy.rs
@@ -0,0 +1,372 @@
+//! `apx deploy` — build and deploy the app to Databricks Apps.
+//!
+//! Flow:
+//!   1. Build wheel (skips UI for agent-only apps, respects UV_OFFLINE)
+//!   2. Copy pyproject.toml into .build/ (needed for agent config at runtime)
+//!   3. Remove .build/.gitignore so DABs syncs all files
+//!   4. `databricks bundle deploy --auto-approve` (uploads .build/ to workspace)
+//!   5. `databricks apps deploy <slug> --source-code-path <workspace_path>`
+//!   6. Poll `databricks apps get` until RUNNING
+
+use clap::Args;
+use indicatif::ProgressBar;
+use serde::Deserialize;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+use std::time::Instant;
+use tracing::debug;
+
+use crate::common::find_app_dir;
+use crate::run_cli_async_helper;
+use apx_core::common::{format_elapsed_ms, read_project_metadata, spinner};
+use apx_core::dotenv::DotenvFile;
+
+/// Default build output directory, relative to app path.
+const DEFAULT_BUILD_DIR: &str = ".build";
+/// How long to wait between deployment status polls (ms).
+const POLL_INTERVAL_MS: u64 = 3_000;
+/// How many times to poll before giving up (~3 min total).
+const POLL_MAX_ATTEMPTS: u32 = 60;
+
+#[derive(Args, Debug, Clone)]
+pub struct DeployArgs {
+    #[arg(
+        value_name = "APP_PATH",
+        help = "Path to the app. Defaults to current working directory"
+    )]
+    pub app_path: Option<PathBuf>,
+
+    #[arg(
+        long = "build-path",
+        default_value = DEFAULT_BUILD_DIR,
+        help = "Path to the build directory, relative to app path"
+    )]
+    pub build_path: PathBuf,
+
+    #[arg(
+        long = "skip-build",
+        help = "Skip the build step and deploy whatever is in the build directory"
+    )]
+    pub skip_build: bool,
+
+    #[arg(
+        long = "profile",
+        help = "Databricks CLI profile to use. Defaults to DATABRICKS_CONFIG_PROFILE from .env"
+    )]
+    pub profile: Option<String>,
+}
+
+pub async fn run(args: DeployArgs) -> i32 {
+    run_cli_async_helper(|| run_inner(args)).await
+}
+
+async fn run_inner(args: DeployArgs) -> Result<(), String> {
+    let app_path = find_app_dir(args.app_path)?;
+    let build_dir = app_path.join(&args.build_path);
+
+    // --- 1. Build ---
+    if !args.skip_build {
+        crate::build::run_build(&app_path, &build_dir).await?;
+    } else if !build_dir.exists() {
+        return Err(format!(
+            "--skip-build specified but build directory does not exist: {}",
+            build_dir.display()
+        ));
+    }
+
+    // --- 2. Post-build fixups ---
+    // Copy pyproject.toml so the agent config is available at runtime.
+    let pyproject_src = app_path.join("pyproject.toml");
+    if pyproject_src.exists() {
+        fs::copy(&pyproject_src, build_dir.join("pyproject.toml"))
+            .map_err(|e| format!("Failed to copy pyproject.toml to build dir: {e}"))?;
+    }
+    // Remove .gitignore — it contains "*" which blocks DABs sync.
+    let gitignore = build_dir.join(".gitignore");
+    if gitignore.exists() {
+        fs::remove_file(&gitignore)
+            .map_err(|e| format!("Failed to remove build .gitignore: {e}"))?;
+    }
+
+    // --- 3. Read metadata + resolve profile ---
+    let meta = read_project_metadata(&app_path)?;
+    let app_slug = &meta.app_name;
+
+    let profile = match args.profile {
+        Some(p) => p,
+        None => {
+            let dotenv = DotenvFile::read(&app_path.join(".env"))?;
+            let vars = dotenv.get_vars();
+            vars.get("DATABRICKS_CONFIG_PROFILE")
+                .cloned()
+                .ok_or_else(|| {
+                    "No Databricks profile found. Set DATABRICKS_CONFIG_PROFILE in .env \
+                     or pass --profile"
+                        .to_string()
+                })?
+        }
+    };
+
+    debug!("deploying app={app_slug} profile={profile}");
+
+    let sp = spinner(&format!("🚀 Deploying {app_slug}..."));
+    let deploy_start = Instant::now();
+
+    // --- 4. Bundle deploy (uploads .build/ to workspace) ---
+    sp.set_message(format!("📦 Uploading {app_slug} to workspace..."));
+    run_bundle_deploy(&app_path, &profile, &sp)?;
+
+    // --- 5. App deploy (create code deployment from workspace path) ---
+    sp.set_message(format!("🔗 Creating app deployment for {app_slug}..."));
+    let workspace_path = resolve_workspace_path(&app_path, &profile, &args.build_path)?;
+    debug!("workspace_path={workspace_path}");
+    run_app_deploy(app_slug, &workspace_path, &profile, &sp)?;
+
+    sp.set_message(format!("⏳ Waiting for {app_slug} to reach RUNNING..."));
+
+    // --- 6. Poll until RUNNING ---
+    poll_until_running(app_slug, &profile, &sp).await?;
+
+    sp.finish_and_clear();
+    println!(
+        "✅ Deployed {} in {}",
+        app_slug,
+        format_elapsed_ms(deploy_start)
+    );
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Bundle deploy
+// ---------------------------------------------------------------------------
+
+fn run_bundle_deploy(app_path: &Path, profile: &str, sp: &ProgressBar) -> Result<(), String> {
+    sp.set_message("📦 Running bundle deploy...".to_string());
+
+    let output = Command::new("databricks")
+        .args([
+            "bundle",
+            "deploy",
+            "--auto-approve",
+            "--profile",
+            profile,
+        ])
+        .current_dir(app_path)
+        .output()
+        .map_err(|e| {
+            format!(
+                "Failed to run `databricks` CLI: {e}\n\
+                 Make sure the Databricks CLI is installed: https://docs.databricks.com/dev-tools/cli/install.html"
+            )
+        })?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        return Err(format!(
+            "databricks bundle deploy failed:\n{stdout}{stderr}"
+        ));
+    }
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Workspace path resolution
+// ---------------------------------------------------------------------------
+
+/// Minimal subset of databricks.yml we need.
+#[derive(Deserialize, Debug)]
+struct BundleConfig {
+    bundle: BundleSection,
+    #[serde(default)]
+    targets: std::collections::HashMap<String, TargetSection>,
+}
+
+#[derive(Deserialize, Debug)]
+struct BundleSection {
+    name: String,
+}
+
+#[derive(Deserialize, Debug, Default)]
+struct TargetSection {
+    #[serde(default)]
+    default: bool,
+}
+
+/// Derive the workspace source-code path from `databricks.yml` + auth info.
+///
+/// Format: `/Workspace/Users/<user>/.bundle/<bundle_name>/<target>/files/<build_path>`
+fn resolve_workspace_path(
+    app_path: &Path,
+    profile: &str,
+    build_path: &Path,
+) -> Result<String, String> {
+    // Read databricks.yml
+    let bundle_config_path = app_path.join("databricks.yml");
+    if !bundle_config_path.exists() {
+        return Err(
+            "databricks.yml not found. Run `databricks bundle init` or use --skip-bundle."
+                .to_string(),
+        );
+    }
+    let bundle_yaml = fs::read_to_string(&bundle_config_path)
+        .map_err(|e| format!("Failed to read databricks.yml: {e}"))?;
+    let bundle_config: BundleConfig = serde_yaml::from_str(&bundle_yaml)
+        .map_err(|e| format!("Failed to parse databricks.yml: {e}"))?;
+
+    let bundle_name = &bundle_config.bundle.name;
+
+    // Find the default target (or fall back to "dev")
+    let target = bundle_config
+        .targets
+        .iter()
+        .find(|(_, v)| v.default)
+        .map(|(k, _)| k.as_str())
+        .unwrap_or("dev");
+
+    // Get current user from auth
+    let user = get_auth_user(profile)?;
+
+    let build_path_str = build_path.to_string_lossy();
+    // Strip leading ./ if present
+    let build_path_clean = build_path_str.trim_start_matches("./");
+
+    Ok(format!(
+        "/Workspace/Users/{user}/.bundle/{bundle_name}/{target}/files/{build_path_clean}"
+    ))
+}
+
+/// Call `databricks auth describe --profile <profile>` and extract the username.
+fn get_auth_user(profile: &str) -> Result<String, String> {
+    let output = Command::new("databricks")
+        .args(["auth", "describe", "--profile", profile, "--output", "json"])
+        .output()
+        .map_err(|e| format!("Failed to call `databricks auth describe`: {e}"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(format!("databricks auth describe failed: {stderr}"));
+    }
+
+    let json: serde_json::Value = serde_json::from_slice(&output.stdout)
+        .map_err(|e| format!("Failed to parse auth describe output: {e}"))?;
+
+    json.get("user")
+        .and_then(|u| u.get("userName"))
+        .and_then(|n| n.as_str())
+        .map(str::to_string)
+        .or_else(|| {
+            // Fall back to top-level "username" field
+            json.get("username")
+                .and_then(|n| n.as_str())
+                .map(str::to_string)
+        })
+        .ok_or_else(|| {
+            format!(
+                "Could not find username in `databricks auth describe` output: {}",
+                serde_json::to_string_pretty(&json).unwrap_or_default()
+            )
+        })
+}
+
+// ---------------------------------------------------------------------------
+// App deploy
+// ---------------------------------------------------------------------------
+
+fn run_app_deploy(
+    app_slug: &str,
+    workspace_path: &str,
+    profile: &str,
+    sp: &ProgressBar,
+) -> Result<(), String> {
+    sp.set_message(format!("🔗 Deploying code for {app_slug}..."));
+
+    let output = Command::new("databricks")
+        .args([
+            "apps",
+            "deploy",
+            app_slug,
+            "--source-code-path",
+            workspace_path,
+            "--profile",
+            profile,
+        ])
+        .output()
+        .map_err(|e| format!("Failed to run `databricks apps deploy`: {e}"))?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        return Err(format!(
+            "databricks apps deploy failed:\n{stdout}{stderr}"
+        ));
+    }
+
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Poll until RUNNING
+// ---------------------------------------------------------------------------
+
+async fn poll_until_running(app_slug: &str, profile: &str, sp: &ProgressBar) -> Result<(), String> {
+    for attempt in 1..=POLL_MAX_ATTEMPTS {
+        tokio::time::sleep(tokio::time::Duration::from_millis(POLL_INTERVAL_MS)).await;
+
+        let output = Command::new("databricks")
+            .args([
+                "apps",
+                "get",
+                app_slug,
+                "--profile",
+                profile,
+                "--output",
+                "json",
+            ])
+            .output()
+            .map_err(|e| format!("Failed to poll deployment status: {e}"))?;
+
+        if !output.status.success() {
+            debug!("poll attempt {attempt}: status command failed, retrying");
+            continue;
+        }
+
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        let state = parse_app_state(&stdout);
+
+        debug!("poll attempt {attempt}: state={state:?}");
+
+        match state.as_deref() {
+            Some("RUNNING") => return Ok(()),
+            Some("ERROR" | "CRASHED") => {
+                return Err(format!(
+                    "App {app_slug} entered state {}: check `databricks apps logs {app_slug} --profile {profile}`",
+                    state.unwrap_or_default()
+                ));
+            }
+            _ => {
+                sp.set_message(format!(
+                    "⏳ [{attempt}/{POLL_MAX_ATTEMPTS}] Waiting for {app_slug} ({})...",
+                    state.as_deref().unwrap_or("unknown")
+                ));
+            }
+        }
+    }
+
+    Err(format!(
+        "Timed out waiting for {app_slug} to reach RUNNING. \
+         Check status with: databricks apps get {app_slug} --profile {profile}"
+    ))
+}
+
+fn parse_app_state(json: &str) -> Option<String> {
+    let value: serde_json::Value = serde_json::from_str(json).ok()?;
+    value
+        .get("app_status")?
+        .get("state")?
+        .as_str()
+        .map(str::to_uppercase)
+}
diff --git a/crates/cli/src/init.rs b/crates/cli/src/init.rs
index c0fefd0c..58ec5c1f 100644
--- a/crates/cli/src/init.rs
+++ b/crates/cli/src/init.rs
@@ -139,6 +139,23 @@ async fn run_inner(mut args: InitArgs) -> Result<(), String> {
     // Eagerly resolve uv (always needed)
     let _uv = apx_core::external::Uv::new().await?;
 
+    // Support `apx init <addon>` as shorthand for `apx init --addons=<addon>`.
+    // If the first positional is a known addon name (not a file path), treat it
+    // as a preset so `apx init agent` works alongside `apx init --addons=agent`.
+    if args.addons.is_none() && !args.no_addons {
+        if let Some(ref p) = args.app_path {
+            let s = p.to_string_lossy();
+            let is_path_like = s.contains('/') || s.contains('\\') || s.contains('.');
+            if !is_path_like {
+                let known = discover_all_addons();
+                if known.iter().any(|(name, _)| name == s.as_ref()) {
+                    args.addons = Some(vec![s.into_owned()]);
+                    args.app_path = None;
+                }
+            }
+        }
+    }
+
     let (workspace_root, app_path, is_member) = resolve_app_path(&mut args)?;
 
     println!("Welcome to apx 🚀\n");
diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs
index 14e73b3d..07f562c8 100644
--- a/crates/cli/src/lib.rs
+++ b/crates/cli/src/lib.rs
@@ -7,6 +7,7 @@
 pub(crate) mod __generate_openapi;
 pub(crate) mod build;
 pub(crate) mod bun;
+pub(crate) mod deploy;
 pub(crate) mod common;
 pub(crate) mod components;
 pub(crate) mod dev;
@@ -39,6 +40,8 @@ enum Commands {
     Init(init::InitArgs),
     /// 🔨 Build the project
     Build(build::BuildArgs),
+    /// 🚀 Deploy the project to Databricks Apps
+    Deploy(deploy::DeployArgs),
     /// 🍞 Run a command using bun
     Bun(bun::BunArgs),
     /// 🧩 Components commands
@@ -183,6 +186,7 @@ async fn run_command(args: Vec<String>) -> i32 {
     match cli.command {
         Some(Commands::Init(init_args)) => init::run(init_args).await,
         Some(Commands::Build(build_args)) => build::run(build_args).await,
+        Some(Commands::Deploy(deploy_args)) => deploy::run(deploy_args).await,
         Some(Commands::Bun(bun_args)) => bun::run(bun_args).await,
         Some(Commands::Components(components_cmd)) => match components_cmd {
             ComponentsCommands::Add(args) => components::add::run(args).await,
diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml
index 8aa4d7a2..50716f24 100644
--- a/crates/core/Cargo.toml
+++ b/crates/core/Cargo.toml
@@ -27,6 +27,7 @@ axum.workspace = true
 reqwest.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+serde_yaml.workspace = true
 tokio.workspace = true
 tokio-stream.workspace = true
 futures-util.workspace = true
diff --git a/crates/core/src/common.rs b/crates/core/src/common.rs
index 9eab0d80..084d7363 100644
--- a/crates/core/src/common.rs
+++ b/crates/core/src/common.rs
@@ -10,6 +10,7 @@ use tokio::io::{AsyncBufReadExt, BufReader};
 use tokio::process::Command;
 
 use crate::api_generator::generate_openapi;
+use crate::dotenv::DotenvFile;
 use crate::external::{Bun, Uv};
 use crate::python_logging::{DevConfig, parse_dev_config};
 
@@ -66,6 +67,11 @@ pub struct ProjectMetadata {
     pub ui_registries: Option<HashMap<String, String>>,
     /// Dev server configuration parsed from `[tool.apx.dev]`.
     pub dev_config: DevConfig,
+    /// Optional `[project.scripts]` entry to use instead of uvicorn.
+    /// When set (e.g. `"start-app"`), the dev server runs `uv run <start_script>`
+    /// instead of `uv run uvicorn <app_entrypoint>`. The script receives `--port`
+    /// and `--reload` so it must accept those arguments (MLflow AgentServer does).
+    pub start_script: Option<String>,
 }
 
 impl ProjectMetadata {
@@ -135,6 +141,11 @@ pub fn read_project_metadata(project_root: &Path) -> Result<ProjectMetadata, Str
     // Parse dev configuration
     let dev_config = parse_dev_config(&pyproject_value, project_root)?;
 
+    // Detect app.yml command — when present and shaped like ["uv", "run", "<script>"],
+    // the dev server uses `uv run <script>` instead of `uv run uvicorn <app_entrypoint>`.
+    // This mirrors the exact command Databricks Apps uses to start the app in production.
+    let start_script = read_app_yml_start_script(project_root);
+
     Ok(ProjectMetadata {
         app_name,
         app_slug,
@@ -144,9 +155,25 @@ pub fn read_project_metadata(project_root: &Path) -> Result<ProjectMetadata, Str
         ui_root,
         ui_registries,
         dev_config,
+        start_script,
     })
 }
 
+/// Read `app.yml` and return the script name if `command` is shaped like
+/// `["uv", "run", "<script>"]`. Returns `None` if `app.yml` is absent or
+/// the command isn't a `uv run` invocation.
+fn read_app_yml_start_script(project_root: &Path) -> Option<String> {
+    let path = project_root.join("app.yml");
+    let contents = fs::read_to_string(&path).ok()?;
+    let doc: serde_yaml::Value = serde_yaml::from_str(&contents).ok()?;
+    let cmd = doc.get("command")?.as_sequence()?;
+    let parts: Vec<&str> = cmd.iter().filter_map(|v| v.as_str()).collect();
+    match parts.as_slice() {
+        ["uv", "run", script, ..] => Some(script.to_string()),
+        _ => None,
+    }
+}
+
 /// Read Python project dependencies from pyproject.toml `[project].dependencies` array.
 /// Returns an empty vec if the section is missing or unparseable.
 pub fn read_python_dependencies(project_root: &Path) -> Vec<String> {
@@ -266,12 +293,31 @@ pub async fn ensure_entrypoint_deps(app_dir: &Path) -> Result<(), String> {
     Ok(())
 }
 
+/// Return true if UV_NATIVE_TLS is enabled — checks the shell environment first,
+/// then falls back to the project's `.env` file. This is needed because `uv sync`
+/// runs before the `.env` file is loaded into the process environment.
+fn resolve_native_tls(app_dir: &Path) -> bool {
+    // Shell env takes precedence
+    if let Ok(val) = std::env::var("UV_NATIVE_TLS") {
+        if val == "1" || val.eq_ignore_ascii_case("true") {
+            return true;
+        }
+    }
+    // Fall back to project .env file
+    DotenvFile::read(&app_dir.join(".env"))
+        .ok()
+        .and_then(|d| d.get_vars().get("UV_NATIVE_TLS").cloned())
+        .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
+        .unwrap_or(false)
+}
+
 /// Run `uv sync` to ensure Python dependencies are installed.
 pub async fn uv_sync(app_dir: &Path) -> Result<(), String> {
     tracing::debug!("Running uv sync in {}", app_dir.display());
 
+    let native_tls = resolve_native_tls(app_dir);
     let uv = Uv::new().await?;
-    uv.sync(app_dir).await?.check("uv").map_err(String::from)?;
+    uv.sync(app_dir, native_tls).await?.check("uv").map_err(String::from)?;
 
     tracing::debug!("uv sync completed successfully");
     Ok(())
@@ -294,8 +340,9 @@ pub async fn generate_version_file(
         .ok_or("Failed to determine version file path")?;
 
     // Try running uv-dynamic-versioning (outputs version string to stdout)
+    let native_tls = resolve_native_tls(app_dir);
     let uv = Uv::new().await?;
-    let version = match uv.tool_run(app_dir, "uv-dynamic-versioning").await {
+    let version = match uv.tool_run(app_dir, "uv-dynamic-versioning", native_tls).await {
         Ok(output) if output.exit_code == Some(0) => {
             let v = output.stdout.trim().to_string();
             if v.is_empty() {
diff --git a/crates/core/src/dev/backend.rs b/crates/core/src/dev/backend.rs
index bbdb514f..ee5e7d21 100644
--- a/crates/core/src/dev/backend.rs
+++ b/crates/core/src/dev/backend.rs
@@ -50,6 +50,10 @@ pub struct BackendConfig {
     pub app_dir: PathBuf,
     pub app_slug: String,
     pub app_entrypoint: String,
+    /// When `Some`, run `uv run <start_script> --port ... --reload` instead of
+    /// `uv run uvicorn <app_entrypoint>`. The script must accept `--port` and
+    /// `--reload` (MLflow AgentServer's `start-app` script does).
+    pub start_script: Option<String>,
     pub host: String,
     pub backend_port: u16,
     pub frontend_port: Option<u16>,
@@ -209,31 +213,58 @@ impl Backend {
 
     // -- private: command construction --
 
-    /// Construct the `uv run uvicorn` command with all env vars.
+    /// Construct the backend command with all env vars.
+    ///
+    /// If `start_script` is set, runs `uv run <script> --port <port> --reload`.
+    /// Otherwise falls back to `uv run uvicorn <app_entrypoint> --port ... --reload`.
     async fn build_uvicorn_command(
         &self,
         log_config: &str,
     ) -> Result<crate::external::ToolCommand, String> {
         let cfg = &self.cfg;
 
-        let mut cmd = UvTool::new("uvicorn")
-            .await?
-            .cmd()
-            .args([
-                &cfg.app_entrypoint,
-                "--host",
-                &cfg.host,
-                "--port",
-                &cfg.backend_port.to_string(),
-                "--reload",
-                "--log-config",
-                log_config,
-            ])
-            .cwd(&cfg.app_dir)
-            .stdin(Stdio::null())
-            .stdout(Stdio::piped())
-            .stderr(Stdio::piped())
-            // APX runtime context
+        let cmd = if let Some(ref script) = cfg.start_script {
+            // MLflow AgentServer path: `uv run start-app --host ... --port ... --reload`
+            // AgentServer._parse_server_args() reads --port and --reload from sys.argv.
+            UvTool::new("uvicorn") // borrow the resolved uv path; tool name is overridden below
+                .await?
+                .uv()
+                .cmd()
+                .args([
+                    "run",
+                    script.as_str(),
+                    "--host",
+                    &cfg.host,
+                    "--port",
+                    &cfg.backend_port.to_string(),
+                    "--reload",
+                ])
+                .cwd(&cfg.app_dir)
+                .stdin(Stdio::null())
+                .stdout(Stdio::piped())
+                .stderr(Stdio::piped())
+        } else {
+            UvTool::new("uvicorn")
+                .await?
+                .cmd()
+                .args([
+                    &cfg.app_entrypoint,
+                    "--host",
+                    &cfg.host,
+                    "--port",
+                    &cfg.backend_port.to_string(),
+                    "--reload",
+                    "--log-config",
+                    log_config,
+                ])
+                .cwd(&cfg.app_dir)
+                .stdin(Stdio::null())
+                .stdout(Stdio::piped())
+                .stderr(Stdio::piped())
+        };
+
+        // APX runtime context (shared by both uvicorn and start-app paths)
+        let mut cmd = cmd
             .env("APX_BACKEND_PORT", cfg.backend_port.to_string())
             .env("APX_DEV_DB_PORT", cfg.db_port.to_string())
             .env("APX_DEV_SERVER_PORT", cfg.dev_server_port.to_string())
diff --git a/crates/core/src/dev/process.rs b/crates/core/src/dev/process.rs
index ff534577..a9abaf40 100644
--- a/crates/core/src/dev/process.rs
+++ b/crates/core/src/dev/process.rs
@@ -58,6 +58,7 @@ impl ProcessManager {
         let dotenv_vars = Arc::new(Mutex::new(dotenv.get_vars()));
         let app_slug = metadata.app_slug.clone();
         let app_entrypoint = metadata.app_entrypoint.clone();
+        let start_script = metadata.start_script.clone();
         let dev_config = metadata.dev_config;
 
         let app_dir = app_dir
@@ -88,6 +89,7 @@ impl ProcessManager {
             app_dir: app_dir.clone(),
             app_slug: app_slug.clone(),
             app_entrypoint,
+            start_script,
             host: host.to_string(),
             backend_port,
             frontend_port,
diff --git a/crates/core/src/dev/proxy.rs b/crates/core/src/dev/proxy.rs
index 78e9f8cf..9df6dbc0 100644
--- a/crates/core/src/dev/proxy.rs
+++ b/crates/core/src/dev/proxy.rs
@@ -173,7 +173,14 @@ pub fn ui_router(frontend_port: u16, dev_token: &str) -> Result<Router, String>
 }
 
 /// Creates the API utilities proxy router for FastAPI docs and OpenAPI schema
-/// Routes: /docs, /redoc, /openapi.json - proxied directly to backend without /api prefix
+/// Routes proxied directly to the Python backend without prefix transformation:
+///   - /docs, /redoc, /openapi.json     — FastAPI interactive docs
+///   - /invocations                      — Databricks Apps / MLflow serving predict endpoint
+///   - /health                           — agent health check
+///   - /.well-known/agent.json           — A2A agent discovery card
+///   - /mcp/sse, /mcp/messages/          — MCP SSE transport endpoints
+///   - /_apx/agent, /_apx/tools,         — APX dev UI pages (must be direct routes so they
+///     /_apx/probe, /_apx/openapi.json     beat the Rust-internal /_apx nest in server.rs)
 pub fn api_utils_router(
     backend_port: u16,
     token_manager: Arc<TokenManager>,
@@ -187,9 +194,24 @@ pub fn api_utils_router(
         forwarded_user_header,
     };
     Ok(Router::new()
+        // FastAPI docs
         .route("/docs", any(api_utils_proxy_handler))
         .route("/redoc", any(api_utils_proxy_handler))
         .route("/openapi.json", any(api_utils_proxy_handler))
+        // Databricks Apps / MLflow serving standard endpoint
+        .route("/invocations", any(api_utils_proxy_handler))
+        // Agent health check
+        .route("/health", any(api_utils_proxy_handler))
+        // A2A agent discovery
+        .route("/.well-known/agent.json", any(api_utils_proxy_handler))
+        // MCP SSE transport
+        .route("/mcp/sse", any(api_utils_proxy_handler))
+        .route("/mcp/messages/", any(api_utils_proxy_handler))
+        // APX agent dev UI routes — direct routes beat the /_apx nest in server.rs
+        .route("/_apx/agent", any(api_utils_proxy_handler))
+        .route("/_apx/tools", any(api_utils_proxy_handler))
+        .route("/_apx/probe", any(api_utils_proxy_handler))
+        .route("/_apx/openapi.json", any(api_utils_proxy_handler))
         .with_state(state))
 }
 
diff --git a/crates/core/src/external/uv.rs b/crates/core/src/external/uv.rs
index b8953167..383896e4 100644
--- a/crates/core/src/external/uv.rs
+++ b/crates/core/src/external/uv.rs
@@ -61,13 +61,23 @@ impl Uv {
     // -----------------------------------------------------------------------
 
     /// Run `uv sync` in the given directory.
-    pub async fn sync(&self, cwd: &Path) -> Result<CommandOutput, CommandError> {
-        self.cmd().arg("sync").cwd(cwd).exec().await
+    /// Pass `native_tls: true` to add `--native-tls` (required on networks with SSL inspection).
+    pub async fn sync(&self, cwd: &Path, native_tls: bool) -> Result<CommandOutput, CommandError> {
+        let mut cmd = self.cmd().arg("sync").cwd(cwd);
+        if native_tls {
+            cmd = cmd.arg("--native-tls");
+        }
+        cmd.exec().await
     }
 
     /// Run `uv tool run <tool>` in the given directory.
-    pub async fn tool_run(&self, cwd: &Path, tool: &str) -> Result<CommandOutput, CommandError> {
-        self.cmd().args(["tool", "run", tool]).cwd(cwd).exec().await
+    /// Pass `native_tls: true` to add `--native-tls` (required on networks with SSL inspection).
+    pub async fn tool_run(&self, cwd: &Path, tool: &str, native_tls: bool) -> Result<CommandOutput, CommandError> {
+        let mut cmd = self.cmd().args(["tool", "run", tool]).cwd(cwd);
+        if native_tls {
+            cmd = cmd.arg("--native-tls");
+        }
+        cmd.exec().await
     }
 
     /// Run `uv run --no-sync python -c <code> [script_args]` in the given directory.
@@ -88,12 +98,21 @@ impl Uv {
     /// Build a `ToolCommand` for `uv build --wheel --out-dir <out_dir>`.
     /// Returns the command for the caller to configure streaming output via `.into_command()`.
     pub fn build_wheel_command(&self, cwd: &Path, out_dir: &Path) -> ToolCommand {
-        self.cmd()
+        let mut cmd = self
+            .cmd()
             .arg("build")
             .arg("--wheel")
             .arg("--out-dir")
             .arg(out_dir)
-            .cwd(cwd)
+            .cwd(cwd);
+        // Use cached packages when network is unavailable (e.g. corporate SSL inspection).
+        // Falls back to network automatically if cache is empty.
+        if std::env::var("UV_OFFLINE").as_deref() == Ok("1")
+            || std::env::var("UV_OFFLINE").as_deref() == Ok("true")
+        {
+            cmd = cmd.arg("--offline");
+        }
+        cmd
     }
 
     /// Run `uv run hatch version` and return the version string.
diff --git a/crates/core/src/resources.rs b/crates/core/src/resources.rs
index 84a048a5..aaaceb39 100644
--- a/crates/core/src/resources.rs
+++ b/crates/core/src/resources.rs
@@ -7,6 +7,9 @@ use rust_embed::RustEmbed;
 /// Embedded templates from `src/apx/templates/`.
 #[derive(RustEmbed)]
 #[folder = "../../src/apx/templates"]
+#[exclude = "**/__pycache__/*"]
+#[exclude = "**/*.pyc"]
+#[exclude = "**/*.pyo"]
 struct Templates;
 
 /// Embedded entrypoint.ts content.
diff --git a/docs/rfcs/agent-protocol.md b/docs/rfcs/agent-protocol.md
new file mode 100644
index 00000000..0b94571f
--- /dev/null
+++ b/docs/rfcs/agent-protocol.md
@@ -0,0 +1,277 @@
+# RFC: Agent Protocol for apx Apps
+
+> **Status:** Draft
+> **Author:** Stuart Gano
+> **Date:** 2026-03-24
+> **Updated:** 2026-03-26
+
+---
+
+## Problem
+
+Building an agent on Databricks Apps requires hand-wiring three distinct layers:
+
+1. **The LLM loop** — calling FMAPI, parsing tool calls, dispatching to handlers, feeding results back, looping until done
+2. **The protocol layer** — implementing `/invocations` (MLflow ResponsesAgent format) and `/.well-known/agent.json` (A2A discovery card) correctly
+3. **Multi-agent orchestration** — treating other agents as tools, calling their `/invocations` endpoints, composing results
+
+The Genie Workbench is a case study: ~1,800 lines of agent protocol wiring on top of working domain logic. Every agent reimplements the same loop.
+
+---
+
+## Proposal
+
+An `Agent` class that takes plain typed functions as tools and handles everything underneath — the LLM loop, protocol compliance, tool dispatch, and OBO auth.
+
+### Developer experience
+
+```python
+# agent.py
+from .core import Dependencies
+from .core.agent import Agent
+
+Workspace = Dependencies.Workspace
+
+def get_weather(city: str) -> str:
+    """Get current weather for a city."""
+    import httpx
+    return httpx.get(f"https://wttr.in/{city}?format=3").text
+
+def query_genie(question: str, space_id: str, ws: Workspace) -> str:
+    """Answer a natural language question using a Genie Space."""
+    return ws.genie.ask(space_id=space_id, question=question).answer or ""
+
+agent = Agent(
+    model="databricks-meta-llama-3-3-70b-instruct",
+    tools=[get_weather, query_genie],
+)
+```
+
+That's the whole file. `pyproject.toml` provides the name and description:
+
+```toml
+[tool.apx.agent]
+name = "genie-workbench"
+description = "Genie Space quality control platform"
+```
+
+### What apx generates
+
+| Endpoint | Purpose |
+|----------|---------|
+| `POST /invocations` | MLflow ResponsesAgent protocol — runs the LLM loop |
+| `GET /.well-known/agent.json` | A2A discovery card (full spec) |
+| `GET /health` | Liveness probe |
+
+### What developers do NOT write
+
+- No LLM loop
+- No FMAPI integration
+- No tool schema definitions (derived from type hints)
+- No tool dispatch
+- No protocol serialization/deserialization
+- No auth bridging (`Workspace` parameters are injected per-request via OBO)
+- No agent card JSON
+
+---
+
+## Protocol details
+
+### `/invocations` — MLflow ResponsesAgent format
+
+**Request:**
+```json
+{
+  "input": [
+    {"role": "user", "content": "What's the weather in NYC and what does Genie say about sales there?"}
+  ],
+  "custom_inputs": {}
+}
+```
+
+**What apx does internally:**
+1. Calls FMAPI with the input messages and tool schemas (OpenAI function calling format)
+2. If FMAPI returns tool calls → dispatches each to the matching Python function
+3. Appends tool results to the message history
+4. Loops until FMAPI returns a final message
+5. Returns the ResponsesAgent response
+
+**Response:**
+```json
+{
+  "output": [
+    {
+      "type": "message",
+      "role": "assistant",
+      "content": [
+        {"type": "output_text", "text": "The weather in NYC is 72°F and sunny. Genie reports..."}
+      ]
+    }
+  ]
+}
+```
+
+### `/.well-known/agent.json` — A2A discovery card
+
+```json
+{
+  "schemaVersion": "1.0",
+  "name": "genie-workbench",
+  "description": "Genie Space quality control platform",
+  "url": "https://genie-workbench.my-workspace.databricksapps.com",
+  "protocolVersion": "0.3.0",
+  "capabilities": {
+    "a2aVersion": "0.3.0",
+    "streaming": false,
+    "multiTurn": true
+  },
+  "provider": {
+    "name": "Databricks",
+    "url": "https://databricks.com"
+  },
+  "authSchemes": [
+    {"type": "bearer", "name": "Databricks OBO token"}
+  ],
+  "skills": [
+    {
+      "id": "get_weather",
+      "name": "get_weather",
+      "description": "Get current weather for a city.",
+      "inputSchema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
+      "outputSchema": {"type": "string"}
+    },
+    {
+      "id": "query_genie",
+      "name": "query_genie",
+      "description": "Answer a natural language question using a Genie Space.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "question": {"type": "string"},
+          "space_id": {"type": "string"}
+        },
+        "required": ["question", "space_id"]
+      },
+      "outputSchema": {"type": "string"}
+    }
+  ]
+}
+```
+
+Note: `Workspace` parameters are excluded from skill schemas — they are OBO-injected per-request and never part of the agent's external interface.
+
+---
+
+## Tool definition
+
+Tools are plain Python functions. Type hints become the schema, docstrings become descriptions.
+
+```python
+def tool_name(param: type, ws: Workspace) -> return_type:
+    """Tool description."""
+    ...
+```
+
+Rules:
+- Parameters typed as `Dependencies.*` (including `Workspace`) are injected via FastAPI DI and excluded from the tool schema
+- All other typed parameters are tool inputs
+- Return type determines the output schema — `str` for plain text, `BaseModel` subclass for structured output
+- Docstring is required and becomes the tool description in both FMAPI and the A2A card
+
+---
+
+## Multi-agent orchestration
+
+Sub-agents are registered by URL. Each sub-agent is treated as a tool that accepts a `message: str` and returns a `str` — its description comes from its `/.well-known/agent.json`.
+
+```python
+agent = Agent(
+    model="databricks-meta-llama-3-3-70b-instruct",
+    tools=[get_weather],
+    sub_agents=[
+        "https://genie-agent.my-workspace.databricksapps.com",
+    ],
+)
+```
+
+At startup, apx fetches each sub-agent's agent card to get its name and description. When the LLM calls a sub-agent tool, apx POSTs to that agent's `/invocations` with the message, forwarding the OBO token.
+
+### Topology
+
+```
+root_agent (APX app)
+├── get_weather (local tool)
+└── genie-agent (sub-agent via /invocations)
+    └── query_genie (tool inside genie-agent)
+```
+
+Each layer is an independently deployable APX app. The root agent composes them without knowing their internals — only their agent cards.
+
+---
+
+## Eval bridge
+
+```python
+from apx.agent import app_predict_fn
+
+predict = app_predict_fn("https://genie-workbench.my-workspace.databricksapps.com")
+results = mlflow.genai.evaluate(
+    data=eval_dataset,
+    predict_fn=predict,
+    scorers=[correctness_scorer],
+)
+```
+
+`app_predict_fn` wraps the `/invocations` endpoint in the ResponsesAgent format expected by `mlflow.genai.evaluate()`.
+
+---
+
+## Implementation phases
+
+### Phase 1 (this PR): Protocol foundation
+- `Agent(model, tools)` class
+- Type hint inspection → tool schemas
+- `Workspace` / `Dependencies.*` parameter exclusion
+- `/invocations` accepting ResponsesAgent format
+- `/.well-known/agent.json` A2A-compliant card
+- `/health`
+
+### Phase 2: LLM loop
+- FMAPI integration via `ws.serving_endpoints.query()`
+- OpenAI-compatible tool call parsing
+- Tool dispatch loop
+- Result serialization back to ResponsesAgent format
+
+### Phase 3: Sub-agents
+- `Agent(sub_agents=[url, ...])`
+- Agent card fetching at startup
+- Sub-agent dispatch via `/invocations`
+- OBO token forwarding
+
+### Phase 4: Eval bridge + streaming
+- `app_predict_fn()`
+- SSE streaming from `/invocations`
+- `apx deploy --agents` (multi-agent deployment)
+
+---
+
+## Design principles
+
+1. **Functions are tools.** No route decorators, no Pydantic models, no `operation_id`. A typed function with a docstring is sufficient.
+
+2. **`Workspace` is the only Databricks-specific concept.** Everything else is plain Python.
+
+3. **Protocol-correct by default.** `/invocations` speaks MLflow ResponsesAgent. `/.well-known/agent.json` speaks A2A. Developers never see these formats.
+
+4. **Composable.** Any APX app can be a sub-agent of another. The root agent only needs a URL.
+
+---
+
+## What this replaces in the Genie Workbench
+
+- 1,757 lines of hand-wired `/invocations` protocol handling (`auto_optimize.py`)
+- ~580 lines of hand-written JSON tool schemas (`create_agent_tools.py`)
+- ~40 lines of tool dispatch tables
+- Separate `auth_bridge.py` / `obo_context()`
+- Separate agent card construction
+- Separate health check endpoints
diff --git a/src/apx/templates/addons/agent/addon.toml b/src/apx/templates/addons/agent/addon.toml
new file mode 100644
index 00000000..afb5f6fa
--- /dev/null
+++ b/src/apx/templates/addons/agent/addon.toml
@@ -0,0 +1,33 @@
+[addon]
+name = "agent"
+description = "🤖 Agent protocol (A2A discovery, /invocations, MCP tools, eval bridge)"
+group = "backend"
+group_display_name = "Backend"
+
+[python]
+dependencies = ["apx-agent>=0.1.0", "httpx>=0.27.0"]
+
+[python.edits]
+imports = [
+    "from .agent import AgentDependency",
+]
+[[python.edits.aliases]]
+code = "AgentContext: TypeAlias = AgentDependency"
+doc = """
+Agent protocol context dependency. Injects the AgentContext (card + tool registry) into a route.
+Recommended usage: `ctx: Dependencies.AgentContext`"""
+
+[[python.edits.aliases]]
+code = "AppClient: TypeAlias = ClientDependency"
+doc = """
+App service principal identity. Works locally and in production.
+Use when the agent acts on behalf of the application itself.
+Recommended usage: `ws: Dependencies.AppClient`"""
+
+[[python.edits.aliases]]
+code = "UserClient: TypeAlias = UserWorkspaceClientDependency"
+doc = """
+Logged-in user's identity via OBO token (X-Forwarded-Access-Token).
+Respects per-user UC grants and audit trails. Production only.
+Use when the agent must act as the person who opened the app.
+Recommended usage: `ws: Dependencies.UserClient`"""
diff --git a/src/apx/templates/addons/agent/pyproject.toml.jinja2 b/src/apx/templates/addons/agent/pyproject.toml.jinja2
new file mode 100644
index 00000000..f43178a1
--- /dev/null
+++ b/src/apx/templates/addons/agent/pyproject.toml.jinja2
@@ -0,0 +1,63 @@
+[project]
+name = "{{app_name}}"
+dynamic = ["version"]
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.119.0",
+    "pydantic-settings>=2.11.0",
+    "uvicorn>=0.37.0",
+    "databricks-sdk>=0.74.0",
+    "httpx>=0.27.0",
+    # MLflow: tracing + experiment tracking (optional — remove if not using MLflow)
+    "mlflow>=2.0",
+]
+
+[dependency-groups]
+dev = [
+    "ty>=0.0.12",
+]
+
+[tool.apx.metadata]
+app-name = "{{app_name}}"
+app-slug = "{{app_slug}}"
+app-entrypoint = "{{app_slug}}.backend.app:app"
+api-prefix = "/api"
+metadata-path = "src/{{app_slug}}/_metadata.py"
+
+[tool.apx.agent]
+name = "{{app_slug}}"
+description = "Add a description of what this agent does"
+# inference: Mosaic AI Model Serving (FMAPI) | tracing: MLflow
+model = "databricks-meta-llama-3-3-70b-instruct"
+instructions = """
+You are a helpful Databricks assistant. You can browse Unity Catalog (catalogs, schemas, tables).
+When a user asks about data or asks what's available, use the tools to look it up — don't guess.
+Replace these example tools with your own in agent_router.py when you're ready to build your app.
+"""
+# instructions = "You are a helpful assistant. ..."  # replace the block above with your own
+# temperature = 0.7      # optional; uses model default when absent
+# max_tokens = 2048      # optional; uses model default when absent
+# max_iterations = 10    # tool-calling loop safety cap (default: 10)
+# vector_search_index = "catalog.schema.index_name"  # RAG: visit /_apx/probe to discover indexes
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+fallback-version = "0.0.0"
+
+[tool.hatch.build.hooks.version]
+path = "src/{{app_slug}}/_version.py"
+template = '''
+version = "{version}"
+'''
+
+[tool.hatch.build]
+artifacts = ["src/{{app_slug}}/__dist__", "src/{{app_slug}}/_metadata.py"]
diff --git a/src/apx/templates/addons/agent/src/base/backend/agent_router.py b/src/apx/templates/addons/agent/src/base/backend/agent_router.py
new file mode 100644
index 00000000..fafc6b3a
--- /dev/null
+++ b/src/apx/templates/addons/agent/src/base/backend/agent_router.py
@@ -0,0 +1,89 @@
+"""Agent tools — replace with your own.
+
+Each function becomes a tool: type hints define the schema, the docstring
+is the description. Dependencies.* parameters are injected by FastAPI and
+excluded from the tool schema.
+
+The three tools below form a working Unity Catalog browser — ask the agent
+"what catalogs do I have?", "list schemas in <catalog>", or
+"show me the tables in <catalog>.<schema>". Use them as a pattern to build
+your own tools, then remove or replace them.
+"""
+
+from .core import Dependencies
+from .core.agent import Agent
+
+AppClient = Dependencies.Client      # app service principal — works locally + in prod
+UserClient = Dependencies.UserClient # logged-in user's identity (OBO) — prod only
+
+
+# ---------------------------------------------------------------------------
+# Example tools: Unity Catalog browser
+# Replace these with your own tools when you're ready.
+# ---------------------------------------------------------------------------
+
+def list_catalogs(ws: AppClient) -> list[str]:
+    """List Unity Catalog catalogs the app can access."""
+    return [c.name for c in ws.catalogs.list() if c.name]
+
+
+def list_schemas(catalog: str, ws: AppClient) -> list[str]:
+    """List schemas inside a Unity Catalog catalog.
+    catalog: catalog name (e.g. 'main' or 'my_catalog')"""
+    return [s.name for s in ws.schemas.list(catalog_name=catalog) if s.name]
+
+
+def list_tables(catalog: str, schema: str, ws: AppClient) -> list[str]:
+    """List tables inside a Unity Catalog schema.
+    catalog: catalog name (e.g. 'main')
+    schema: schema name (e.g. 'default')"""
+    return [
+        t.name for t in ws.tables.list(catalog_name=catalog, schema_name=schema) if t.name
+    ]
+
+
+agent = Agent(tools=[list_catalogs, list_schemas, list_tables])
+
+
+# ---------------------------------------------------------------------------
+# What else you can do (visit /_apx/setup for guided configuration)
+# ---------------------------------------------------------------------------
+#
+# LoopAgent — let the agent iterate until the task is done:
+#   Wrap your Agent: agent = LoopAgent(Agent(tools=[...]), max_iterations=10)
+#   Or toggle from /_apx/setup (Agent Pattern section).
+#
+# RAG — Mosaic AI Vector Search:
+#   Set vector_search_index in pyproject.toml [tool.apx.agent], or visit
+#   /_apx/setup to discover indexes and generate a search tool automatically.
+#
+# Sub-agents: consume other agents as tools (A2A)
+# ---------------------------------------------------------------------------
+# Your agent can call other APX agents as tools. Each sub-agent's skills are
+# auto-discovered via /.well-known/agent.json and exposed to the LLM.
+# OBO auth tokens are forwarded automatically at every hop.
+#
+# Option A — config-driven (recommended for deploy flexibility):
+#   In pyproject.toml [tool.apx.agent]:
+#     sub_agents = ["$PRICING_AGENT_URL", "$INVENTORY_AGENT_URL"]
+#   Then set env vars per environment:
+#     PRICING_AGENT_URL=http://localhost:8001          # dev
+#     PRICING_AGENT_URL=https://pricing.ws.databricksapps.com  # prod
+#
+# Option B — hardcoded in code:
+#   agent = Agent(
+#       tools=[list_catalogs, list_schemas, list_tables],
+#       sub_agents=["https://pricing.ws.databricksapps.com"],
+#   )
+#
+# ---------------------------------------------------------------------------
+# MAS (Multi-Agent Supervisor) compatibility
+# ---------------------------------------------------------------------------
+# This agent is MAS-consumable out of the box. It exposes:
+#   GET  /.well-known/agent.json  — A2A discovery card (name, skills, auth)
+#   POST /invocations              — MLflow ResponsesAgent protocol
+#   POST /mcp                      — MCP stateless HTTP transport
+# To register in MAS: deploy this app, then add its URL as a sub-agent.
+#
+# Auth chain: User → MAS (OBO) → This Agent (OBO forwarded) → Sub-Agents
+# Authorization + X-Forwarded-Access-Token headers pass through every hop.
diff --git a/src/apx/templates/addons/agent/src/base/backend/core/_agent/__init__.py b/src/apx/templates/addons/agent/src/base/backend/core/_agent/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/apx/templates/addons/agent/src/base/backend/core/_agent/_dependency.py b/src/apx/templates/addons/agent/src/base/backend/core/_agent/_dependency.py
new file mode 100644
index 00000000..c205e424
--- /dev/null
+++ b/src/apx/templates/addons/agent/src/base/backend/core/_agent/_dependency.py
@@ -0,0 +1,102 @@
+"""_AgentDependency — LifespanDependency bridge to apx_agent runtime + dev UI."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import APIRouter, FastAPI, Request
+
+from apx_agent import AgentContext, BaseAgent, setup_agent
+from apx_agent._dev import build_dev_ui_router, inject_create_tool_meta
+from apx_agent._mcp import _build_mcp_components
+from apx_agent._models import _get_agent_instance, _set_agent_instance
+
+from .._base import LifespanDependency
+
+logger = logging.getLogger(__name__)
+
+
+def _auto_import_agent_router() -> None:
+    """Import agent_router and register the module-level ``agent`` variable."""
+    if _get_agent_instance() is not None:
+        return
+    import importlib
+    parts = __name__.split(".")
+    if len(parts) >= 4:
+        backend_pkg = ".".join(parts[:-3])
+        try:
+            module = importlib.import_module(f"{backend_pkg}.agent_router")
+            candidate = getattr(module, "agent", None)
+            if isinstance(candidate, BaseAgent):
+                _set_agent_instance(candidate)
+        except ImportError:
+            pass
+
+
+class _AgentDependency(LifespanDependency):
+    @asynccontextmanager
+    async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, None]:
+        _auto_import_agent_router()
+        _agent = _get_agent_instance()
+
+        if _agent is None:
+            logger.warning(
+                "No agent registered. Set a module-level `agent = LlmAgent(tools=[...])` in agent_router.py."
+            )
+            app.state.agent_context = None
+            yield
+            return
+
+        ctx = await setup_agent(app, _agent)
+        if ctx is None:
+            yield
+            return
+
+        # Dev mode: inject create_tool when agent_router.py is editable
+        from apx_agent._ui_edit import _find_agent_router_path
+        if _find_agent_router_path() is not None:
+            inject_create_tool_meta(ctx)
+
+        # Setup MCP
+        try:
+            from contextlib import nullcontext
+            from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+            mcp_server, mcp_transport = _build_mcp_components(ctx, app, ctx.config.api_prefix)
+            app.state.mcp_server = mcp_server
+            app.state.mcp_transport = mcp_transport
+            mcp_http_manager = StreamableHTTPSessionManager(mcp_server, stateless=True)
+            app.state.mcp_http_manager = mcp_http_manager
+            logger.info("MCP server enabled at /mcp/sse (SSE) and /mcp (stateless HTTP)")
+            mcp_lifecycle = mcp_http_manager.run()
+        except ImportError:
+            app.state.mcp_server = None
+            app.state.mcp_transport = None
+            app.state.mcp_http_manager = None
+            logger.warning("mcp package not installed — /mcp endpoints disabled.")
+            from contextlib import nullcontext
+            mcp_lifecycle = nullcontext()
+
+        async with mcp_lifecycle:
+            yield
+
+    @staticmethod
+    def __call__(request: Request) -> AgentContext | None:
+        return getattr(request.app.state, "agent_context", None)
+
+    def get_routers(self) -> list[APIRouter]:
+        _auto_import_agent_router()
+        if _get_agent_instance() is None:
+            return []
+        return _get_agent_instance().get_tool_routers()
+
+    def get_root_routers(self) -> list[APIRouter]:
+        try:
+            from ..._metadata import api_prefix as _api_prefix
+        except ImportError:
+            _api_prefix = "/api"
+        return [build_dev_ui_router(api_prefix=_api_prefix)]
+
+
+AgentDependency = _AgentDependency
diff --git a/src/apx/templates/addons/agent/src/base/backend/core/agent.py b/src/apx/templates/addons/agent/src/base/backend/core/agent.py
new file mode 100644
index 00000000..48514f1b
--- /dev/null
+++ b/src/apx/templates/addons/agent/src/base/backend/core/agent.py
@@ -0,0 +1,55 @@
+"""Agent protocol addon — re-exports from apx_agent package.
+
+Define agent tools as plain typed functions and register them with Agent():
+
+    from .core import Dependencies
+    from .core.agent import Agent
+
+    def query_genie(question: str, space_id: str, ws: Dependencies.UserClient) -> str:
+        \"\"\"Answer a natural language question using a Genie Space.\"\"\"
+        return ws.genie.ask(space_id=space_id, question=question).answer or ""
+
+    agent = Agent(tools=[query_genie])
+"""
+
+# Core runtime (from apx-agent package)
+from apx_agent import (  # noqa: F401
+    Agent,
+    AgentCard,
+    AgentConfig,
+    AgentContext,
+    AgentTool,
+    AfterToolHook,
+    BaseAgent,
+    BeforeToolHook,
+    HandoffAgent,
+    InputGuardrailFn,
+    InvocationRequest,
+    InvocationResponse,
+    LlmAgent,
+    LoopAgent,
+    Message,
+    OutputGuardrailFn,
+    ParallelAgent,
+    RouterAgent,
+    SequentialAgent,
+    app_predict_fn,
+    create_app,
+    set_custom_output,
+    setup_agent,
+)
+from apx_agent._models import (  # noqa: F401
+    A2ACapabilities,
+    A2AAuthScheme,
+    A2AProvider,
+    A2ASkill,
+    OutputItem,
+    OutputTextContent,
+    _ToolFn,
+    _get_agent_instance,
+    _set_agent_instance,
+)
+
+# Dependency (FastAPI lifespan bridge)
+from ._agent._dependency import _AgentDependency  # noqa: F401
+AgentDependency = _AgentDependency
diff --git a/src/apx/templates/base/src/base/backend/core/_base.py b/src/apx/templates/base/src/base/backend/core/_base.py
index 5fad35fb..bede7c3e 100644
--- a/src/apx/templates/base/src/base/backend/core/_base.py
+++ b/src/apx/templates/base/src/base/backend/core/_base.py
@@ -42,6 +42,12 @@ def get_routers(self) -> list[APIRouter]:
         """
         return []
 
+    def get_root_routers(self) -> list[APIRouter]:
+        """Override to contribute routers mounted at the application root (no api prefix).
+        Use for protocol routes such as /.well-known/*, /health, /invocations.
+        """
+        return []
+
     @classmethod
     def depends(cls) -> Any:
         return Depends(cls.__call__)
diff --git a/src/apx/templates/base/src/base/backend/core/_factory.py b/src/apx/templates/base/src/base/backend/core/_factory.py
index c6fe105b..1980af99 100644
--- a/src/apx/templates/base/src/base/backend/core/_factory.py
+++ b/src/apx/templates/base/src/base/backend/core/_factory.py
@@ -5,6 +5,7 @@
 from functools import lru_cache
 
 from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
 
 from ..._metadata import api_prefix, app_name, dist_dir
 from ._base import LifespanDependency
@@ -64,12 +65,26 @@ async def _composed_lifespan(app: FastAPI):
 
     app = FastAPI(title=app_name, lifespan=_composed_lifespan)
 
+    # Allow cross-origin requests so Databricks UI clients (Genie Code, AI Playground)
+    # can reach /mcp and /invocations from a different origin. Databricks Apps enforces
+    # auth at the proxy level before requests reach the app, so wildcard origins are safe.
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
     api_router: APIRouter = create_router()
     for dep in all_deps:
         for r in dep.get_routers():
             api_router.include_router(r)
     app.include_router(api_router)
 
+    for dep in all_deps:
+        for r in dep.get_root_routers():
+            app.include_router(r)
+
     for router in routers or []:
         if router is not api_router:
             app.include_router(router)
diff --git a/tests/init_integration.rs b/tests/init_integration.rs
index 8c0446f6..f16313e4 100644
--- a/tests/init_integration.rs
+++ b/tests/init_integration.rs
@@ -215,3 +215,108 @@ fn test_init_creates_project_structure() {
 
     println!("All assertions passed!");
 }
+
+#[test]
+#[ignore] // Slow test - run with `cargo test --test init_integration -- --ignored`
+fn test_init_with_agent_addon() {
+    let wheel_dir = TempDir::new().expect("Failed to create wheel temp dir");
+    let project_dir = TempDir::new().expect("Failed to create project temp dir");
+    let app_path = project_dir.path().join("my-agent");
+
+    // Build wheel
+    let build_output = Command::new("maturin")
+        .args(["build", "--out", wheel_dir.path().to_str().unwrap()])
+        .current_dir(project_root())
+        .output()
+        .expect("Failed to run maturin build");
+    if !build_output.status.success() {
+        let stderr = String::from_utf8_lossy(&build_output.stderr);
+        panic!("maturin build failed:\n{stderr}");
+    }
+
+    let wheel_path = find_wheel(wheel_dir.path());
+
+    // Run apx init with agent addon (no UI)
+    let init_output = Command::new("uvx")
+        .args([
+            "--from",
+            wheel_path.to_str().unwrap(),
+            "apx",
+            "init",
+            "--name",
+            "my-agent",
+            "--addons",
+            "agent",
+            "--profile",
+            "WORKSPACE",
+            app_path.to_str().unwrap(),
+        ])
+        .output()
+        .expect("Failed to run uvx apx init");
+
+    if !init_output.status.success() {
+        let stderr = String::from_utf8_lossy(&init_output.stderr);
+        let stdout = String::from_utf8_lossy(&init_output.stdout);
+        panic!("apx init --addons agent failed:\nstdout: {stdout}\nstderr: {stderr}");
+    }
+
+    let app_slug = "my_agent";
+    let backend = app_path.join("src").join(app_slug).join("backend");
+
+    // agent_router.py scaffolded
+    let agent_router = backend.join("agent_router.py");
+    assert!(
+        agent_router.exists(),
+        "agent_router.py should exist at {}",
+        agent_router.display()
+    );
+    let agent_router_content =
+        fs::read_to_string(&agent_router).expect("Failed to read agent_router.py");
+    assert!(
+        agent_router_content.contains("Agent(tools="),
+        "agent_router.py should register Agent(tools=...)"
+    );
+
+    // core/agent.py scaffolded
+    let agent_core = backend.join("core").join("agent.py");
+    assert!(
+        agent_core.exists(),
+        "core/agent.py should exist at {}",
+        agent_core.display()
+    );
+
+    // pyproject.toml contains [tool.apx.agent]
+    let pyproject = app_path.join("pyproject.toml");
+    let pyproject_content = fs::read_to_string(&pyproject).expect("Failed to read pyproject.toml");
+    assert!(
+        pyproject_content.contains("[tool.apx.agent]"),
+        "pyproject.toml should contain [tool.apx.agent]"
+    );
+    assert!(
+        pyproject_content.contains("name = \"my-agent\""),
+        "pyproject.toml [tool.apx.agent] should have name = \"my-agent\""
+    );
+    assert!(
+        pyproject_content.contains("model = "),
+        "pyproject.toml [tool.apx.agent] should have a model field"
+    );
+
+    // httpx + mcp dependencies added (from addon.toml)
+    assert!(
+        pyproject_content.contains("httpx"),
+        "pyproject.toml should contain httpx dependency"
+    );
+    assert!(
+        pyproject_content.contains("mcp"),
+        "pyproject.toml should contain mcp dependency"
+    );
+
+    // No UI directory (pure backend agent)
+    let ui_dir = app_path.join("src").join(app_slug).join("ui");
+    assert!(
+        !ui_dir.exists(),
+        "ui/ should NOT exist for a backend-only agent project"
+    );
+
+    println!("Agent addon assertions passed!");
+}