`tool_output` stream events don't distinguish between success and error states

[habema]

Problem

When an agent invokes a tool, the tool_output stream event always has the same structure regardless of whether the tool succeeded or failed. Both successful results and error messages end up in the output field with no indication of which is which.

This makes it impossible for a UI to properly present tool execution results - it can't tell if the output represents a successful tool result or an error message.

Current Behavior

RunItemStreamEvent(
    name="tool_output",
    item=ToolCallOutputItem(
        output="some result",  # Could be success OR error message
        raw_item={...},
        agent=agent
    )
)

My question; is this behavior intentional? Are there design reasons for not distinguishing success/error states? Is extending the ToolCallOutputItem data model to have an is_error flag a welcome contribution?

[seratch]

I haven't verified this yet, but once I am done with other tasks, I will check this in depth.

[habema]

Sure. Here is a code snippet to help you test this:

import asyncio

from agents import Agent, RunItemStreamEvent, Runner, ToolCallOutputItem, function_tool


@function_tool
def get_current_weather(city: str) -> str:
    """Get the current weather for a given city"""
    raise Exception("Not implemented")

async def main():
    agent = Agent(
        name="Weather Agent",
        model="gpt-4.1-mini",
        tools=[get_current_weather],
    )

    result = Runner.run_streamed(agent, input="Get the current weather in Tokyo")
    async for event in result.stream_events():
        if isinstance(event, RunItemStreamEvent) and isinstance(event.item, ToolCallOutputItem):
            print(event.item)

if __name__ == "__main__":
    asyncio.run(main())

[habema]

Hello @seratch, any updates on this?

[seratch]

Sorry for my slow response here. Currently, the framework always returns str in the case of an error while running a function tool. The default behavior is https://github.com/openai/openai-agents-python/blob/v0.2.11/src/agents/tool.py#L298-L300 an you can customize the string by passing failure_error_function when initializing a function tool.

If you want to tell success or error, I'd recommend catching any errors within a function tool and return a structured output result, which could include either successful result or error.

[habema]

Could adding a flag in ToolCallOutputItem to indicate success/failure be a good idea?

[seratch]

At this moment, I personally don't think so.

[habema]

For now I've been using a solution similar to the one you mentioned, but this implies that if i want to properly display tool call failures in my UI, all tools i define must catch all errors internally, and all use the same structured output item. It works, but its not clean and not very maintainable. Would be great if this was closed with a "known limitation" label, and addressed in the future.

[github-actions]

This issue is stale because it has been open for 7 days with no activity.

[github-actions]

This issue was closed because it has been inactive for 3 days since being marked as stale.