apx-agent 0.4.0

Standalone agent runtime for Databricks Apps — MCP, A2A, /invocations, tool routing

apx-agent

Build governed Databricks agents. Write a Python object — apx-agent compiles it to whichever Databricks runtime you target.

uv add apx-agent
uv run apx-agent doctor                          # check auth & environment first
uv run apx-agent agents scaffold my-agent
uv run apx-agent agents deploy my-agent.yaml --target apps

doctor verifies your Databricks auth, tooling, and config before you scaffold. scaffold writes my-agent.yaml by default. deploy reads that spec, generates the Databricks Apps project at deploy time, and prints the App URL when done.

uv run apx-agent agents scaffold my-agent --no-yaml
cd my-agent && uv run apx-agent agents run --reload

Use --no-yaml when you want the editable project directory and local FastAPI dev UI first.

Know what you're pointed at

apx-agent status prints the active Databricks profile and project/target — offline, no API call — so you can confirm context before you deploy:

$ apx-agent status
profile: fe-stable
project: payroll-coworker
target:  apps

--prompt emits a compact one-liner (apx:payroll-coworker(apps) ▸ fe-stable). It's safe in an async/cached prompt segment (e.g. starship [custom], powerlevel10k async), but the CLI cold-starts in ~1s, so don't call it on every render of a synchronous PS1. For an instant, zero-overhead prompt the same facts read straight from the shell:

apx_ps1() {
  local p="${DATABRICKS_CONFIG_PROFILE:-DEFAULT}"
  [ -f pyproject.toml ] && grep -q '\[tool.apx.agent\]' pyproject.toml && printf 'apx ▸ %s ' "$p"
}
setopt PROMPT_SUBST 2>/dev/null; PROMPT='$(apx_ps1)'"$PROMPT"

---

What is apx-agent?

Building agents on Databricks means dealing with a stack of systems that all speak different languages: LLM APIs have incompatible wire formats, memory backends have different interfaces, conversation history looks different depending on the framework, and trace schemas differ by SDK. Wiring all of that together correctly — and keeping it working as the stack evolves — is the problem nobody wants to have.

apx-agent is the normalization layer. You declare what your agent should be. apx-agent makes it work and makes it observable, regardless of what's underneath.

[tool.apx.agent]
name = "payroll-coworker"
model = "databricks/claude-3-7-sonnet"
instructions = "You are a payroll analyst..."

[tool.apx.agent.memory]
type = "delta"
table_name = "main.payroll.agent_memory"

[tool.apx.agent.data]
catalog = "main"
schema = "payroll"

That declaration becomes: an agent grounded in its schema before the first question, durable memory that persists across sessions, a dev UI that surfaces tool calls and conversation correctly regardless of which underlying API format produced them, and a deployment target that enforces Unity Catalog grants per-caller without any per-agent configuration.

What gets normalized so you don't have to think about it:

Layer	What apx-agent hides
LLM API format	Responses API and chat-completions traces both surface identically in the dev UI
Conversation history	One canonical message format across all agent types and frameworks
Memory backends	Delta Lake, Lakebase, or in-memory — same interface, declared not implemented
Observation	Tool calls, spans, and conversation deltas normalized before they reach any renderer
Governance	Identity passthrough, UC grants, and audit logging wired from the declaration

You write a Python object or a TOML block. The normalization work is apx-agent's job.

---

Three agent types cover most use cases:

LlmAgent	The base. You own the loop: tools, hooks, guardrails, iteration cap.
DataAgent	One line over a Unity Catalog schema. Grounded in real columns, runs as the calling user.
CoworkerAgent	Joins two source systems on a shared key. Persona, join key, objective.

Deploy to Databricks Apps or Mosaic AI Model Serving — same agent definition, one flag changes the target.

---

Quickstart

Python 3.11+ required.

1. Install

uv add apx-agent

2. Scaffold a YAML spec

uv run apx-agent agents scaffold my-agent

The default scaffold writes my-agent.yaml in the current directory. Fill in any $CATALOG / $SCHEMA placeholders before deploying.

3. Deploy from YAML

uv run apx-agent agents deploy my-agent.yaml --target apps

deploy generates the Apps project from the YAML in a temporary directory, bundles it, and creates a Databricks App. It prints the URL when done.

4. Optional local project

uv run apx-agent agents scaffold my-agent --no-yaml
cd my-agent && uv sync
uv run apx-agent agents run --reload

Use --no-yaml only when you need an editable project directory. FastAPI starts on :8000; chat at /_apx/agent, view traces at /_apx/traces, author new tools via the New Tool modal and inspect live tool schemas in the right panel of the Edit page (/_apx/edit) — the standalone /_apx/tools page is retired and redirects there. agent.py edits are picked up on restart — pass --reload (off by default) for auto-reload during local dev.

Something not working? Run uv run apx-agent doctor — checks Python, uv, Databricks CLI, auth, and project layout. Prints a Fix: line for anything wrong.

See docs/get-started/quickstart.md for the full walkthrough.

---

LlmAgent — you control the loop

LlmAgent (aliased as Agent) is an LLM + tools + a loop. You decide what it can call, when it stops, and what happens before and after each step.

from apx_agent import LlmAgent, uc_function_tool, genie_tool

agent = LlmAgent(
    instructions="Investigate customer accounts.",
    tools=[
        uc_function_tool("main.tools.lookup_account"),
        genie_tool("abc123", description="Answer billing questions"),
    ],
    max_iterations=10,
    # memory="persistent",   # durable semantic recall across sessions
)

Every hook is optional. None requires subclassing.

from apx_agent import run_once

# Invoke the agent (no HTTP request needed)
result = run_once(agent, "Look up account 42.")
print(result)

Compose loops explicitly. LoopAgent iterates until a condition is met; SequentialAgent pipelines agents in order; ParallelAgent fans out; HandoffAgent routes conversationally.

from apx_agent import SequentialAgent

investigation = SequentialAgent(
    agents=[presence_check, lineage_trace, code_analysis, synthesis],
    instructions="Investigate why data is missing.",
)

See docs/agents/composition.md for the full composition reference.

---

DataAgent — one line over a UC schema

from apx_agent import DataAgent

agent = DataAgent("main", "sales")

That's a working agent. It knows the tables and columns in main.sales before the first question — no SHOW TABLES at runtime, no discovery prompt, no hallucinated schema.

Schema discovery priority (first match wins):

1. Baked schema — .apx/schema.json, written from the UC Tables API when the project is generated: apx-agent agents scaffold --no-yaml, or at apx-agent agents deploy my-agent.yaml time. Ships with your code.
2. Live introspection — pass ws=WorkspaceClient() for fresh schema at construction time.
3. Explicit override — pass tables={"orders": ["id(bigint)", ...]} for tests.
4. Ungrounded fallback — discovers schema with SQL on the first turn.

# Live introspection
from databricks.sdk import WorkspaceClient
agent = DataAgent("main", "sales", ws=WorkspaceClient())

# Add persona, Genie space, vector search, or UC functions
agent = DataAgent(
    "main", "sales",
    persona="a revenue analyst",
    genie_space="abc123",
    vector_index="main.sales.product_docs",
    extra_tools=[uc_function_tool("main.tools.send_alert")],
)

Governance: deploy once, everyone runs as themselves. The app forwards each caller's OAuth token per request, and Unity Catalog enforces their grants on their data. See docs/safety/identity-passthrough.md.

See docs/agents/data-agent.md for the full reference.

---

CoworkerAgent — join two source systems

Two source systems landed in a UC schema. One business entity links them. One question neither system can answer alone.

from apx_agent import CoworkerAgent

agent = CoworkerAgent(
    "main", "payroll",
    persona="a payroll operations analyst",
    join_key="employee ID",
    objective="surface mismatches between hours worked and paychecks issued",
    # memory="persistent",  # remember facts across sessions
)

The join_key and objective are woven into the agent's grounded instructions. Common patterns:

Use case	System A	System B	Join key
Payroll reconciliation	Kronos (hours worked)	Workday (paychecks)	employee ID
Quote-to-cash	Salesforce (deals)	NetSuite (invoices)	opportunity ID
Onboarding / offboarding	Workday (employment)	Okta (access)	employee ID
Warranty & entitlement	ServiceNow (cases)	SAP (contracts)	asset serial number
Order status	Oracle ERP (orders)	TMS (freight)	PO / shipment number
Claims integrity	Epic (chart)	Claims system (coding)	patient encounter

apx-agent agents scaffold my-coworker --template coworker   # writes my-coworker.yaml; add --no-yaml for a local project

See docs/agents/coworker.md for the full reference.

---

See what you built

Every deployed agent ships with /_apx/topology — an interactive graph of agents, tools, sub-agents, and the UC / Genie / Vector Search / serving resources they reach. Click any node for its details.

See docs/get-started/dev-ui.md for the full /_apx/* surface: chat, traces, eval, tool authoring in the Edit page's New Tool modal, probe.

---

Examples

12 worked examples in python/examples/:

Example	What it shows
customer_triage	HandoffAgent + memory + UC tools
data-triage-agent	6-step SequentialAgent (presence → lineage → pipeline → genie → code → synthesis)
entity-resolution-agent	Fuzzy account match via Vector Search + HandoffAgent
memory_demo	MemoryStore + ExampleStore — recall across handoffs
slack-agent	Slack-initiated runs as the Slack user's Databricks identity
+ 7 more	data-inspector, eligibility-agent, contract-parsing, shortage-intelligence, explain-my-bill, apx-builder, agent-hub

---

CLI

apx-agent agents scaffold <name>   # writes <name>.yaml spec (add --no-yaml for a full project dir)
apx-agent agents run               # local FastAPI dev server (/_apx/agent) — run inside a --no-yaml project
apx-agent agents deploy <name>.yaml    # generate project from the spec + deploy to Databricks Apps
apx-agent eval run evalset.jsonl   # run against deployed endpoint with LLM judge
apx-agent traces list --agent <name>   # recent MLflow traces filtered by apx.* attributes
apx-agent fleet list --where team=revops   # bulk ops across many agents (tag/backfill/redeploy; dry-run by default)
apx-agent label start --uc-name cat.sch.my_agent --judge domain_quality --scale 1-5 --assignee [e-mail]
                                   # open SME labeling session → prints Review App URL + run-id
apx-agent label align --uc-name cat.sch.my_agent --judge domain_quality --run <run-id>
                                   # align the judge on SME ratings (requires: pip install 'apx-agent[align]')
apx-agent doctor                   # diagnose auth, deps, project layout

See docs/get-started/cli.md for the full surface.

---

Docs

Topic	Doc
Quickstart	docs/get-started/quickstart.md
Running agents (run, stream, max_iterations)	docs/agents/llm-agent.md
DataAgent reference	docs/agents/data-agent.md
CoworkerAgent reference	docs/agents/coworker.md
Agent composition	docs/agents/composition.md
Routing (RouterAgent, HandoffAgent)	docs/agents/routing.md
Tools — governed primitives	docs/tools/overview.md
Tools — custom (@tool, MCP)	docs/tools/custom-tools.md
Multi-agent (sub-agents, A2A)	docs/multi-agent/overview.md
Sessions + memory	docs/running/sessions-and-memory.md
Guardrails and callbacks	docs/safety/callbacks.md
Identity passthrough + OBO	docs/safety/identity-passthrough.md
Compliance (Watchdog, audit log)	docs/safety/compliance.md
Deploy targets	docs/deploy/apps-vs-model-serving.md
Evaluation	docs/evaluate/overview.md
Configuration (pyproject.toml)	docs/reference/configuration.md
Coming from ADK or OpenAI Agents SDK	docs/get-started/migration.md

---

Coming from ADK or OpenAI Agents SDK?

See docs/get-started/migration.md for a concept-by-concept translation. The key mappings:

ADK / OpenAI	apx-agent
Agent(name, instructions, model)	LlmAgent(name, instructions) or Agent(...) — set the model via the [tool.apx.agent] model field in pyproject.toml
Runner.run()	run_once(agent, "prompt")
@function_tool / @tool	@tool
input_guardrails=[fn]	input_guardrails=[fn] (same param name)
@input_guardrail tripwire	raise PermissionError in before_agent_callback
before_tool_callback	before_tool or before_tool_callback (both accepted)
MemoryService	MemoryStore
Handoffs	HandoffAgent

---

For AI coding assistants

The repo ships an llms.txt index of all documentation URLs. Add the docs as a local MCP server in Claude Code:

claude mcp add apx-agent-docs --transport stdio -- \
  uvx --from mcpdoc mcpdoc \
  --urls "apxAgent:https://raw.githubusercontent.com/stuagano/apx-agent/main/llms.txt" \
  --transport stdio

---

License

Apache 2.0 — see LICENSE.