Agents SDK の web_fetch、v0.28.0 以上で PDF も Markdown にして読める

Cloudflare Agents SDK に、エージェントが Web ページや PDF を読むための web_fetch ツールが加わった。使うには Agents SDK v0.28.0 以上が要る。changelog のコード例では、Pi Durable の extension registry に webFetchTool を install してから harness を開く順序になっている。取得先のホスト、レスポンスサイズ、タイムアウト、リダイレクトは開発者が制御できる。

読める対象は Web ページ、PDF、対応する Office 文書だ。テキストへの変換には Workers AI の Markdown Conversion が使われる。Markdown for Agents に対応したサイトからは Markdown を直接要求し、JSON はモデル向けに整形して渡す。公式 changelog の掲載日は2026年10月12日だ。

registry に install してから Harness.open() に渡す

changelog に載っている TypeScript 版のコード例は次のとおりだ。

import { webFetchTool } from "agents/webfetch/pi";

export class MyAgent extends DurableObject<Env> {
  // ...

  readonly harness = new PiHarness({
    harness: async ({ storage, context }) => {
      this.registry.install({
        name: "web-tools",
        tools: [webFetchTool({ binding: this.env.AI })],
      });

      // ...

      return Harness.open(
        storage,
        { models, registry: this.registry },
        context,
      );
    },
  });
}

// ... は changelog 側の省略で、models や this.registry をどこで定義するかは示されていない。読み取れる流れは三段だ。registry に web-tools という名前でツールを登録し、その registry を Harness.open() の第 2 引数に渡し、webFetchTool() には binding として this.env.AI を渡す。Workers AI の binding が env に AI という名前で生えている前提のコードになっている。

モデルに返ってくる値

モデルは URL を渡すだけでよく、ページ本文と一緒に次の 3 つを受け取る。

• 最終 URL
• HTTP ステータス
• content type

長いページは一度に全文が返るわけではない。小さな section に分かれて返り、続きを読むための offset が付く。モデルはその offset を使って次の部分を要求する。長い PDF を読ませる場合、モデルが何度かツールを呼んで読み進める形になる。

ステータスと content type が本文と一緒に返るので、エラーページの中身をそのまま事実として扱うかどうかをモデル側で判断できる材料はある。ただし、モデルが実際にどう使うかは changelog には書かれていない。

取得先とサイズを絞る

制御できる項目として changelog が挙げるのは、取得を許すホスト、レスポンスサイズ、タイムアウト、リダイレクトの 4 つだ。設定キーの名前、既定値、上限値は changelog の本文にはない。

取得する URL を決めるのはモデルだ。社内向けのエージェントに入れるなら、許可ホストを先に決めておくのが自然な順序になる。リダイレクトも制御対象に入っているので、許可したホストから別ホストへ飛ばされるケースの扱いもあわせて決めておきたい。

web_search と一緒に渡したとき

web_search ツールも同じエージェントに渡すと、モデルには「web_search が返したページは web_fetch で読む」ように指示が入る。検索結果の要約だけで答えずに、本文を取りに行かせる組み合わせだ。これはモデルへの指示であって、changelog から読める範囲では、必ず web_fetch を経由させる強制の仕組みではない。

PiHarness を使わない構成

web_fetch はどの harness でも動くとされている。SDK には AI SDK と TanStack AI のアダプターが含まれる。それ以外の harness を使う場合や、モデルを呼ばずにページだけ取りたい場合は、agents/webfetch から fetchWeb()、windowWebFetchPage()、renderWebFetchPage() を使う。この直接取得には Durable Object もブラウザも要らない。Durable Object 上で harness を動かす構成は OpenCode の harness の記事 でも扱った。

導入前に確認しておく点をまとめると次のようになる。

• agents パッケージが v0.28.0 以上か
• Worker の env に Workers AI の binding（例では AI）があるか
• 取得を許すホストとリダイレクトの扱いを決めたか
• PiHarness、AI SDK、TanStack AI、独自 harness のどれで組み込むか

3 つの関数の引数や戻り値の形は changelog には載っていないので、使う前に型定義を見ることになる。