Authoring Agents with MLflow ResponsesAgent and Agent Framework

1.Where agent development happens on Databricks

Databricks gives you several ways to build an agent, from no-code to fully custom. AI Playground is the no-code option. You pick an LLM, add tools and chat with the agent to test it, then export the result to code. Knowledge Assistant lets you build and optimize domain-specific AI chatbots through an interface. The Supervisor Agent is a managed way to orchestrate other agents and tools, Genie Agents among them. For full control you build a custom agent in Python, and Databricks says this route supports agents written with any authoring library and is integrated with MLflow Tracing. The Agent Bricks CLI (Beta) is a code-first alternative to building custom agents on Databricks Apps. It scaffolds, runs and deploys custom code agents from the command line.

Sources1

2.The Databricks Apps agent template

If you build a custom agent and deploy it on Databricks Apps, you control the agent code, the server configuration and the deployment workflow. Start from a template rather than wiring the pieces together yourself. The agent-openai-agents-sdk template contains three things: an agent built with the OpenAI Agents SDK, starter code for a conversational REST API with a chat UI, and code to evaluate the agent using MLflow. Its server is the MLflow AgentServer, an async FastAPI server with built-in tracing and observability. The AgentServer exposes a /responses endpoint and takes care of request routing, logging and error handling.

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Sources2

3.ResponsesAgent: one interface for any framework

This is what connects the agent framework to MLflow. You can author an agent with any framework and then wrap it in ResponsesAgent, and the wrapped agent works out of the box with AI Playground, Agent Evaluation and Agent Monitoring. You also get typed Python authoring classes, automatic tracing that combines streamed responses into a single trace, and compatibility with the OpenAI Responses schema. ResponsesAgent also supports multi-agent systems, streaming output, tool-calling confirmation and long-running tools. It can return several messages per turn, intermediate tool-calling messages included, which the documentation says improves quality and conversation management.

In code, the class-based form is a subclass of ResponsesAgent. You implement predict, which takes a ResponsesAgentRequest and returns a ResponsesAgentResponse, and predict_stream, which yields ResponsesAgentStreamEvent objects. On Model Serving agents use this class-based structure. On Databricks Apps the MLflow AgentServer instead serves module-level functions decorated with @invoke() and @stream(), which use the same request, response and stream-event types.

from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

Sources23

4.Giving the agent tools

An agent becomes useful when it can query databases, search documents or call APIs. You give it those abilities by connecting MCP servers. The template already includes one MCP server connection. To add more, you configure additional MCP servers in your agent code and grant the permissions they need in databricks.yml. Some operations don't need external data, such as transformations, calculations and utilities. For those you define local function tools that run in the same process as the agent.

Databricks also provides managed MCP servers. For example, Unity Catalog functions are reachable through a managed server for their catalog and schema: the built-in function system.ai.python_exec, which lets an agent run Python code, is available through the managed MCP server for the system.ai schema. The databricks-mcp package provides DatabricksMCPClient to list a server's tools and to work out the Unity Catalog resources the agent needs. The same managed-server approach covers Genie and AI Search, where the agent needs access to the resources behind each server, such as CAN_RUN on a Genie space or SELECT on an AI Search index.

mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/functions/system/ai/python_exec",
    workspace_client=workspace_client,
)

tools = mcp_client.list_tools()

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

@ ? 
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

Sources24

5.Streaming, errors and custom inputs

With streaming, the agent sends its answer in chunks as it generates it instead of waiting for the full response. In ResponsesAgent you send a series of output_text.delta events that all share one item_id, then finish with a response.output_item.done event that has the same item_id and the complete text. The done event tells Databricks to record the output with MLflow tracing, aggregate the stream in Unity Gateway inference tables, and show the full answer in AI Playground. If an error happens during streaming, it arrives with the last token under databricks_output.error, and the client is responsible for handling it.

Sometimes an agent needs extra inputs, such as client_type or session_id, or extra outputs, such as links to retrieval sources, that should stay out of the chat history. ResponsesAgent has two fields for this: custom_inputs and custom_outputs. In your agent code you read the extra inputs from request.custom_inputs. One documented limit: the Agent Evaluation review app does not support rendering traces for agents with additional input fields.

To deploy to Model Serving, you log the agent with MLflow, register it in Unity Catalog and deploy it. When you log, pass the resources the agent depends on, such as its serving endpoint, Unity Catalog functions and vector search indexes, so Model Serving can grant access at deployment. For managed MCP servers, DatabricksMCPClient().get_databricks_resources() returns the resources the server needs. The example below sets the registry URI to Unity Catalog beforehand with mlflow.set_registry_uri.

with mlflow.start_run():
    logged_model_info = mlflow.pyfunc.log_model(
        artifact_path="mcp_agent",
        python_model=agent_script,
        resources=resources,
    )

UC_MODEL_NAME = "main.default.databricks_docs_mcp_agent"
registered_model = mlflow.register_model(logged_model_info.model_uri, UC_MODEL_NAME)

agents.deploy(
    model_name=UC_MODEL_NAME,
    model_version=registered_model.version,
)

Sources25

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Every tool an agent uses must have a resource grant in databricks.yml.Why is that wrong?

   Only external resources such as additional MCP servers need grants. Local function tools run inside the agent process and need none.

   Covered in Giving the agent tools

2. 2.Adding custom_inputs to an agent has no effect on any of the evaluation tooling.Why is that wrong?

   The documentation names one limit: the Agent Evaluation review app cannot render traces for agents that have additional input fields.

   Covered in Streaming, errors and custom inputs