feat: control display of tool execution results to llm

[mhordynski]

Feature description

It should be possible to pass custom objects from tools to the agent output without exposing them to the LLM.

The idea is to introduce a special container or type that is handled in such a way that only a selected subset of its data is displayed or returned to the LLM, while the complete object is preserved in the ToolCallResult.

Motivation

One example use case is retrieving a list of users along with their secret keys for post-execution handling by the agent. In this scenario, the secret keys must not be exposed to the LLM, but they should still be available in the tool execution result.

Additional context

Option 1:

class ToolResult[TRes, TMetadata]:
    result: TRes
    metadata: TMetadata

async def my_tool( inp: str):
    return ToolResult[str, dict](result="Hello world", metadata={"internal-state": {"a": 1, "b": 2}})

Option 2:

class MyResult(ToolResult):
    data: dict

    def render(self):
         return self.data["public"]