Issues with Custom Agents on Free Edition

[taniumalloy]

I have ran into a few issues while learning how to use Custom Agents in Databricks Apps that I would like to call out - both to help others and hopefully motivate platform improvements.

1. The only model that seems to work is databricks-meta-llama-3-3-70b-instruct, but I only found that out through a DataExpert.io YouTube video. It would be nice if the app templates would default to this or at least provide some guidance on the Free Edition limitations page. 
2. Recent changes to MCP have caused issues with the default OpenAI Agents SDK app template. You have to manually add "mcp<2.0.0" to the dependencies in pyproject.toml to get it up and running. 
3. The second message from the user starts to cause errors. I haven't figured out how to solve this, but it is something related to the format of the message chain. For example:

{
  "detail": "Unhandled item type or structure: {'status': None, 'content': [{'text': \"Hello, it's nice to meet you. Is there something I can help you with or would you like to chat?\", 'type': 'output_text'}], 'role': 'assistant', 'type': 'message'}"
}​

[DoTA · Accepted solution]

On the third issue (errors starting from the second user message) - this looks like it's coming from how the app's own conversation-history handling deals with items from the OpenAI Agents SDK's output, rather than from the model or MCP layer itself.

The payload in your error - {'status': None, 'content': [{'text': ..., 'type': 'output_text'}], 'role': 'assistant', 'type': 'message'} - is a standard "message" item shape from the Agents SDK / Responses API (roughly what you'd see from a run's output items, or from to_input_list()). If the app template keeps its own conversation state by appending previous turns and only handles a subset of item shapes (e.g. assumes content is a flat string, or only expects tool-call/tool-output items), a "message" item where content is a list of output_text objects can trip up whatever code path builds the next request - which would explain why it works on the first turn (no history yet) and breaks as soon as a prior assistant message has to be folded back in.

Worth checking wherever the template reconstructs the input/message history between turns for a type or role check that doesn't have a branch for type == "message" with a list-shaped content. If you're passing to_input_list() straight from the SDK, that should normalize this correctly already, so the bug is more likely in custom glue code the template layers on top of it.

On the other two - the model limitation and the mcp<2.0.0 pin both sound like genuine doc/template maintenance gaps rather than expected behavior, so worth filing them as explicit feedback (in-product feedback widget or docs feedback link) so they get tracked rather than staying tribal knowledge from a YouTube video.

[taniumalloy]

For the issue I described above, it may be related to the model I am using: "databricks-meta-llama-3-3-70b-instruct". I got it to work by using this on the agent input:

        # messages = [i.model_dump() for i in request.input]
        messages = to_chat_completions_input([i.model_dump() for i in request.input])

[taniumalloy]

Following up on this, there is an open PR for this issue that details what is going on:

https://github.com/databricks/app-templates/pull/256

I added this code to utils.py

def to_runner_input(request: ResponsesAgentRequest) -> list[dict]:
    """Normalize Responses history into items Runner.items_to_messages accepts.

    Chat UIs echo prior assistant messages as type=message with output_text parts
    and no id (and Pydantic dump adds status=None). The Agents SDK Chat Completions
    converter rejects that shape. Keep function_call / function_call_output as-is so
    tool history still round-trips; do not run to_chat_completions_input here.
    """
    messages: list[dict] = []
    for item in request.input:
        dumped = item.model_dump(exclude_none=True)
        if (
            dumped.get("type") == "message"
            and dumped.get("role") == "assistant"
            and "id" not in dumped
        ):
            dumped["id"] = str(uuid4())
        messages.append(dumped)
    return messages

Then use the function to normalize messages to Chat Completions API schema with an id attribute for assistant messages:

# messages = [i.model_dump() for i in request.input]
messages = to_runner_input(request)
result = Runner.run_streamed(agent, input=messages)