RFC: Agent protocol support for apx apps

[stuart-gano]

What this is

Agents are the right abstraction for custom domain knowledge in Genie Code. Genie alone can't do everything — it doesn't know your ERP schema, your billing rules, or your internal data model. But an agent can. And if you build that agent as a Databricks App, it shows up automatically in Genie Code as a custom MCP server.

This PR adds the template integration to make that first-class in APX.

---

Architecture

The agent runtime is a standalone pip package: apx-agent. It provides:

• MCP endpoints — /mcp (stateless HTTP for Genie Code) and /mcp/sse (SSE for Claude Desktop/Cursor)
• A2A discovery — /.well-known/agent.json with tool schemas
• /invocations — MLflow ResponsesAgent chat endpoint with tool-calling loop
• Tool routing — type-hinted Python functions become /api/tools/<name> routes
• Agent composition — Sequential, Parallel, Router, Loop, Handoff patterns
• Dev UI — chat interface, code editor, setup wizard, tool suggestion via LLM

This PR adds the thin APX template layer that wires apx-agent into the apx add agent scaffold.

---

What this PR changes (~1,400 lines)

Template (src/apx/templates/addons/agent/)

• addon.toml — declares apx-agent>=0.1.0 dependency + Python AST edits for Dependencies aliases
• pyproject.toml.jinja2 — project template with [tool.apx.agent] config section
• agent_router.py — scaffolded tool example (what users edit)
• agent.py — barrel re-export from apx-agent package
• _dependency.py — ~100-line LifespanDependency shim that calls apx_agent.setup_agent()

Rust CLI

• deploy.rs — apx deploy command for Databricks Apps deployment
• init.rs — agent addon discovery during apx init
• build.rs / proxy.rs — agent-aware build and dev proxy

RFC doc

• docs/rfcs/agent-protocol.md — design rationale and architecture

Integration test

• tests/init_integration.rs — verifies apx init --addons=agent generates the right scaffold

---

The pattern in 5 lines

from .core import Dependencies
from .core.agent import Agent

def get_billing_summary(customer_id: str, months: int, ws: Dependencies.Client) -> dict:
    """Get a customer's recent billing history with tier breakdown and payment status."""
    rows = _run_sql(ws, f"SELECT * FROM billing_history WHERE customer_id = '{customer_id}' LIMIT {months}")
    return {"bills": rows}

agent = Agent(tools=[get_billing_summary])

APX + apx-agent handle the rest: MCP server, /invocations loop, tool routing, MLflow traces.

---

Where APX fits in the agent stack

	MAS (Supervisor Agent)	APX
Role	Orchestration — routes to sub-agents	Dev toolkit — builds the agents
Registration	Declarative: resource IDs	Code-first: Python functions
Dev loop	Deploy → wait (2-5 min)	uvicorn --reload (instant)

MAS is "how you wire agents together." APX is "how you build them."

---

Test plan

• apx add agent generates template that imports from apx-agent
• Deploy app named mcp-* → appears in Genie Code MCP server list
• Genie Code agent mode calls tools via /mcp stateless HTTP
• /mcp/sse works (Claude Desktop, Cursor)
• /invocations works (direct API / MLflow eval)
• All verified against explain-my-bill-agent example