Set a readable root-span request and response

[adamgurary]

Fixes #29

Context

This issue is one finding from a hands-on evaluation (a Critical User Journey run) of building, tracing, and improving an agent that runs off Databricks. The agent is a LangGraph rebuild of a customer-notes workflow. It runs on a laptop and calls the Databricks Foundation Model API endpoint databricks-claude-opus-4-8. Its MLflow traces are written to Unity Catalog.

Full writeup:

• Summary: https://databricks.atlassian.net/wiki/spaces/~7120200d4c393f21a14d67bba42ffb3e92a69f/pages/6623789187
• Walkthrough: https://databricks.atlassian.net/wiki/spaces/~7120200d4c393f21a14d67bba42ffb3e92a69f/pages/6624084274

Environment

• MLflow 3.14.0, LangGraph 1.2.7, LangChain 1.3.11, databricks-langchain 0.17.0, databricks-sdk 0.94.0, openai 2.24.0, Python 3.12.
• Databricks workspace: logfood (adb-2548836972759138). SQL warehouse 79415a9aea7a3a7e.
• MLflow experiment: customer-notes-agent-uc (id 2824204872263693).
• UC trace location: catalog home_adam_gurary, schema personal_agents, table prefix customer_notes.
• Per run: roughly 1.6M input tokens across about 14 to 16 LLM calls.

Instrumentation skill should produce a readable root-span request and response

Summary

When a coding agent used the MLflow instrumentation skills to trace a LangGraph agent, the top of the trace showed an unreadable blob instead of the run inputs and outputs. The @mlflow.trace decorator on the entry point auto-recorded the compiled LangGraph object as the request and the entire final state dict as the response. The root span showed neither the customer name going in nor the note coming out.

Steps to reproduce

1. Ask a coding agent to instrument a LangGraph agent's entry point with @mlflow.trace per the skills.
2. Run the agent, open the trace, look at the root span request and response.

Actual behavior

The root-span request was the Python repr of the compiled graph object. The root-span response was the full accumulated state dictionary (transcript plus all research plus draft). Both were unreadable in the UI.

Root cause

The skill applied @mlflow.trace to a function whose input is a large framework object and whose output is a large state dict, without guiding the agent to record a compact, human-readable summary instead.

Expected behavior and proposed fix

The MLflow instrumentation skills should teach the coding agent to set a compact, readable request and response on the root span, rather than letting @mlflow.trace capture raw framework objects. For a LangGraph agent, that means the meaningful inputs (the customer and date) and the meaningful outputs (the output path and a short preview). The goal is that the trace reads well in the UI by default.

Evidence and references

Fixed in the agent by hand-setting compact root-span fields (commit 64c0d647d). See the walkthrough linked above.

[adamgurary]

Hi — just rebased this onto the latest main (was 12 commits behind). The PR adds two reference commits to the databricks-mlflow-evaluation skill: one guiding agents to set a readable root-span request and response, and one teaching the correct override pattern (using update_current_trace vs span.set_outputs() which is overwritten by the decorator). No CI gaps to resolve. Would appreciate a review when you have a moment — happy to address any feedback.