langchain-siteshot

A LangChain tool that takes website screenshots with the Site-Shot API. The page is rendered in a real Chromium browser and the image goes back to the model as an image content block, so a multimodal agent can look at the page.

• Tool name: capture_screenshot
• Arguments the model fills in: url, full_page, width, height, format (png, jpeg, webp), country (optional)
• Returns a short text block and the image as base64 (response_format="content_and_artifact"). The raw image bytes and capture metadata are on ToolMessage.artifact and are not sent to the model.
• Built on the official site-shot SDK.

Installation

pip install -U langchain-siteshot

Credentials

Get a key at https://www.site-shot.com/start/. A confirmed account's API key comes with the free plan: 100 API captures a month, no card needed; paid plans start at $5/mo for 2,000. Accounts confirmed before 2026-10-30 switch it on with one button on the dashboard or on /start/; an account that has had a paid plan before does not get the free plan. Plans are listed at https://www.site-shot.com/pricing/.

Set the key as an environment variable, or pass api_key= to the tool:

export SITESHOT_API_KEY="your-api-key"

Quickstart

from langchain_siteshot import SiteShotScreenshot

tool = SiteShotScreenshot()

# With a ToolCall you get a ToolMessage: content for the model, artifact for you.
message = tool.invoke(
    {
        "args": {"url": "https://www.wikipedia.org/", "full_page": True},
        "id": "1",
        "name": tool.name,
        "type": "tool_call",
    }
)
message.content    # [{"type": "text", ...}, {"type": "image", "base64": ..., "mime_type": "image/png"}]
with open("wikipedia.png", "wb") as f:
    f.write(message.artifact["image"])

In an agent

Use a model that accepts images in tool results: Claude, Gemini, or OpenAI through the Responses API (ChatOpenAI(..., use_responses_api=True)). OpenAI's Chat Completions API takes only text in tool results.

from langchain.agents import create_agent
from langchain_siteshot import SiteShotScreenshot

agent = create_agent(
    model="claude-sonnet-5",
    tools=[SiteShotScreenshot()],
)
agent.invoke(
    {"messages": [{"role": "user", "content": "Take a screenshot of https://www.wikipedia.org/ and describe the layout."}]}
)

Configuration

Settings on the tool are fixed by you and hidden from the model:

Free plan and limits

What the free plan includes:

• 100 API captures a month, no card needed; it renews every month. It comes with a confirmed account's key; an account that has had a paid plan before does not get it (see Credentials).
• Renders from the default location or the US only. Any other country is refused with an error instead of an image, and the refused request still counts toward the month's 100. The tool tells the model to retry without country or with country="US".
• One capture at a time. Agents that issue parallel tool calls would send concurrent requests, and a second concurrent request may be refused with HTTP 429. That is why max_concurrency defaults to 1: calls from one tool instance wait for each other instead.
• When the month's captures are used up, the API answers 403 until the plan renews, and the tool returns an error message saying so.

Country proxies, storage and schedules are on paid plans from $5/mo. See https://www.site-shot.com/pricing/.

Other limits worth knowing:

• Viewport width 100-8000 px, height 100-20000 px.
• WebP output is capped at 16,383 px per side (a libwebp limit).
• Very tall full-page images can still be large in tokens; lower full_page_max_height or pass {"scaled_width": 800} in default_params.

Country

When a country is requested (by the model or in default_params), the tool also sends strict_country=True. Without it, Site-Shot silently falls back to a US vantage point when that country has no capacity, and the model would be told the page came from a country it did not come from. With it, the capture fails with CountryUnavailableError instead, and the text block's "rendered from DE" is true. Set default_params={"strict_country": False} to accept the fallback; the text block then says "country requested: DE" and that the render may have come from the US.

Errors

The tool maps the SDK's error classes to messages an agent can act on:

Invalid arguments (width out of range, unknown format, a country that is not a two-letter code) are rejected by the tool's schema before any capture is spent.

Development

pip install -e . pytest pytest-asyncio pytest-socket "langchain-tests==1.1.9"
make test                                   # unit tests, network disabled
SITESHOT_API_KEY=... make integration_tests # live API, spends about five captures

License

MIT