Skip to content

View Image Tool Provider

The ViewImageToolProvider allows agents to view images from their execution environment.

ViewImageToolProvider

stirrup.tools.view_image.ViewImageToolProvider 

ViewImageToolProvider(
    exec_env: CodeExecToolProvider | None = None,
    *,
    name: str = "view_image",
    description: str | None = None,
)

Bases: ToolProvider

Tool provider for viewing images from an execution environment.

Can be used with an explicit exec_env or will auto-detect from the Agent's session state. Works regardless of tool ordering in the Agent.

Examples:

from stirrup.clients.chat_completions_client import ChatCompletionsClient

client = ChatCompletionsClient(model="gpt-5")

Explicit exec_env

exec_env = LocalCodeExecToolProvider() agent = Agent( client=client, name="assistant", tools=[exec_env, ViewImageToolProvider(exec_env)], )

Auto-detect (any order works)

agent = Agent( client=client, name="assistant", tools=[ViewImageToolProvider(), LocalCodeExecToolProvider()], )

Initialize ViewImageToolProvider.

Parameters:

Name Type Description Default
exec_env CodeExecToolProvider | None

Optional execution environment. If None, will auto-detect from the Agent's session state.

 None
name str

Tool name (default: "view_image").

 'view_image'
description str | None

Tool description (default: standard description).

 None
Source code in src/stirrup/tools/view_image.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(
    self,
    exec_env: CodeExecToolProvider | None = None,
    *,
    name: str = "view_image",
    description: str | None = None,
) -> None:
    """Initialize ViewImageToolProvider.

    Args:
        exec_env: Optional execution environment. If None, will auto-detect
            from the Agent's session state.
        name: Tool name (default: "view_image").
        description: Tool description (default: standard description).

    """
    self._exec_env = exec_env
    self._name = name
    self._description = description

__aenter__ async 

__aenter__() -> Tool[ViewImageParams, ToolUseCountMetadata]

Enter async context: resolve exec_env and return view_image tool.

Source code in src/stirrup/tools/view_image.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
async def __aenter__(self) -> Tool[ViewImageParams, ToolUseCountMetadata]:
    """Enter async context: resolve exec_env and return view_image tool."""
    # Import here to avoid circular dependency
    from stirrup.core.agent import _SESSION_STATE

    state = _SESSION_STATE.get(None)
    agent_exec_env = state.exec_env if state else None

    if self._exec_env is not None:
        # Explicit exec_env provided - validate it matches agent's exec_env
        if agent_exec_env is not None and self._exec_env is not agent_exec_env:
            raise ValueError(
                f"ViewImageToolProvider exec_env ({type(self._exec_env).__name__}) "
                f"does not match Agent's exec_env ({type(agent_exec_env).__name__}). "
                "Use the same exec_env instance or omit exec_env to auto-detect."
            )
        exec_env = self._exec_env
    else:
        # Auto-detect from session state
        if agent_exec_env is None:
            raise RuntimeError(
                "ViewImageToolProvider requires a CodeExecToolProvider. "
                "Either pass exec_env explicitly or include a CodeExecToolProvider "
                "in the Agent's tools list."
            )
        exec_env = agent_exec_env

    return exec_env.get_view_image_tool(
        name=self._name,
        description=self._description,
    )

Usage

from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import LocalCodeExecToolProvider, ViewImageToolProvider

client = ChatCompletionsClient(model="gpt-5")
agent = Agent(
    client=client,
    name="image_viewer",
    tools=[
        LocalCodeExecToolProvider(),
        ViewImageToolProvider(),  # Auto-detects exec environment
    ],
)

async with agent.session() as session:
    await session.run("Create a chart with matplotlib and view it")

How It Works

  1. The ViewImageToolProvider is initialized with an optional exec_env parameter
  2. If not provided, it automatically detects the execution environment from the session
  3. The view_image tool reads image files from the execution environment
  4. Images are returned as ImageContentBlock objects for the model to see