Stirrup入門｜ArtificialAnalysis製・ベストプラクティス内蔵の軽量AIエージェントビルダー解説

Stirrup入門として、ArtificialAnalysis製の軽量AIエージェントビルダーを公式情報ベースで解説する。Stirrupは、モデル自身に進め方を委ね、コンテキスト管理や基盤ツールといったベストプラクティスを最初から内蔵した、MITライセンスのPythonエージェントフレームワークだ。本記事では設計思想から導入、ツール/メモリ組み込み、モデル選択、他フレームワークとの比較、実運用の注意点までを通しで整理する。

エージェント用フレームワークは数多いが、Stirrupは「枠組みを増やすのではなく、減らす」立ち位置で異彩を放っている。開発元は各社LLMをベンチマークで横断比較しているArtificialAnalysisで、GitHubスター数は400を超え、軽量な出発点テンプレートとして注目を集めている。

30秒で理解する

まず要点だけを先に押さえる。詳細は各セクションで掘り下げる。

・Stirrupは、ベンチマークで知られるArtificialAnalysisが公開したPython製の軽量AIエージェントビルダー（フレームワーク兼テンプレート）
・ライセンスはMIT。pip install stirrupで導入でき、クライアントとAgentを作ってタスク文字列を渡すだけで動く
・設計思想は「モデルに任せる」。Claude Codeのように、進め方をモデル自身に決めさせ、フレームワークは余計な制約をかけない
・code_exec（コード実行）・web_fetch・web_searchといった基盤ツールと、コンテキスト自動要約が標準装備
・独自ツールはPydanticで定義してtools=に足すだけ。MCPクライアントにも対応し、外部ツール群を取り込める
・OpenAI互換API・LiteLLM経由でClaude/GPT/Geminiなどを1行で差し替えられ、ベンチマークを見ながらモデルを選べる
・コード実行はローカル/Docker/E2Bサンドボックスから選択。本番では隔離前提

つまりStirrupは、「エージェントの定型部分（基盤ツール・コンテキスト管理）は用意するが、進め方はモデルに委ねる」という最小主義のAIエージェントビルダーだ。

Stirrupとは（開発元ArtificialAnalysisの信頼性）

Stirrupは、ArtificialAnalysisが公開した「エージェントを作るための軽量フレームワーク、ないし出発点となるテンプレート」だ。公式の説明では「The lightweight foundation for building agents（エージェント構築のための軽量基盤）」と表現されている。

そもそもエージェントとは何か、という前提を整理したい場合は、まずAIエージェントとは？仕組み・種類・代表的OSSフレームワークを初心者向けに解説【2026年版】を読むと本記事の位置づけがつかみやすい。Stirrupはそこで扱う「自律エージェント」を、最小コードで組むための土台にあたる。

注目すべきは開発元だ。ArtificialAnalysisは、各社のLLMを知能指数（Intelligence Index）・出力速度・トークン単価で横断比較するベンチマークサイトを運営しているチームである。日々モデルの実測値を公開しており、「どのモデルでエージェントがどれだけ性能を出すか」を最も観測してきた立場にいる。そのチームが多数の先行エージェントを分析し、共通して効くパターンを抽出してフレームワーク化したのがStirrupだ。

数値面の現況を押さえておく。

・ライセンス: MIT（商用・私的利用とも可、要帰属表示）
・実装言語: Python（非同期API中心、asyncioベース）
・GitHubスター: 400超 / フォーク 40超
・バージョン: v0.1系（若く、APIは変わりうる）
・提供形態: インストール可能なパッケージ、かつフルカスタム用のテンプレート

「パッケージとしても、自分で全部書き換えるテンプレートとしても使える」二面性が、Stirrupの実用上のポイントになる。すぐ動かしたい人はパッケージで、挙動を細部まで握りたい人はテンプレートをforkして改造する、という二つの入口がある。

このクラスタの近接記事として、グラフで実行フローを組むLangGraph入門｜マルチエージェント・ステートマシン構築の基本と他フレームワークとの違い、役割分担で協調させるCrewAI入門｜マルチエージェント協調フレームワークの基本とLangGraph/AutoGenとの違いも合わせて読むと、設計思想の違いが立体的に見えてくる。

設計思想（軽量＋ベストプラクティス内蔵）

Stirrupの設計は、3つの原則に集約される。

・モデル中心（model-centric）——「Stirrupは脇に退き、モデルが自分でタスクの進め方を選べるようにする（Claude Codeに近い）。多くのフレームワークは硬直したワークフローを押し付け、結果を劣化させうる」。つまり制御構造を増やさないことが思想の中心
・ベストプラクティス内蔵——先行する優れたエージェントを分析し、コンテキスト管理や基盤ツールといった「効くパターン」を最初から組み込む
・カスタマイズ性——インストール可能なパッケージとしても、フルカスタム実装のテンプレートとしても使える

この思想を、エージェントの動作ループとして図にすると次のようになる。

重要なのは、図の中に「ワークフローを規定するノード」が存在しないことだ。多くのフレームワークが「計画→実行→検証」のような固定フローを持つのに対し、Stirrupは「Agentがツールを呼び、観測を受け取り、また判断する」という素朴なループだけを回す。次に何をするかはモデルが決める。Claude Codeを使ったことがあれば、あの「指示すると勝手に進めていく」感覚に近いと考えればよい。

そして、このループを実用に耐えさせるための「地味だが効く部分」——コンテキストが上限に近づいたときの自動要約、隔離されたコード実行、web取得——をフレームワーク側が肩代わりする。これが「軽量＋ベストプラクティス内蔵」の正体だ。

インストールと最小エージェント

導入はpip一発だ。用途に応じてオプションコンポーネントを足す。

# 最小インストール
pip install stirrup

# オプション込み（litellm / docker / e2b / mcp / browser など）
pip install 'stirrup[all]'

# 個別に足す例（LiteLLM経由でClaude等を使う場合）
pip install 'stirrup[litellm]'

次が最小エージェントだ。クライアントを作り、Agentに渡し、session()の中でrun()にタスクを渡す。実行前にOPENROUTER_API_KEYを環境変数にセットしておく（web検索を使う場合はBRAVE_API_KEYも）。

import asyncio
from stirrup import Agent
from stirrup.clients.chat_completions_client import ChatCompletionsClient


async def main() -> None:
    # OpenAI互換エンドポイント（ここではOpenRouter）に接続
    client = ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-sonnet-4.5",
    )
    agent = Agent(client=client, name="agent", max_turns=15)

    async with agent.session(output_dir="./output/getting_started_example") as session:
        finish_params, history, metadata = await session.run(
            """オーストラリアの直近3年の人口を調べ、
            matplotlibで年ごとの人口を示す簡単なチャートを作成して。"""
        )


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

このコードだけで、エージェントはweb検索で人口を調べ、code_execでmatplotlibを動かしてチャートを生成し、output_dirに成果物を書き出す。session()がツールの寿命とファイル入出力を管理してくれるため、後始末を自分で書く必要がない。

LiteLLM経由でAnthropic Claudeなどを使う場合は、クライアントを差し替えるだけだ。base_urlを意識せずプロバイダ名で指定できる。

from stirrup.clients.litellm_client import LiteLLMClient

# pip install 'stirrup[litellm]' が前提
# LiteLLMがサポートする任意のプロバイダをmodel_slugで指定できる
client = LiteLLMClient(
    model_slug="anthropic/claude-sonnet-4-5",
    max_tokens=200_000,
)

# clientを渡すだけ。モデル情報はclient.model_slugから引き継がれる
agent = Agent(
    client=client,
    name="claude_agent",
)

ポイントは、モデルの切り替えがクライアント1行で済むことだ。ベンチマークを見て「このタスクはGPT系が強い」「コスト重視ならDeepseek」といった判断を、エージェント本体のコードを触らずに反映できる。

ツール/メモリの組み込み

Stirrupには2つのツールプロバイダが標準で同梱される。

code_execの実行環境は、ローカル・Docker・E2Bサンドボックスから選べる。手元検証はローカル、本番は隔離されたDockerやE2B、という使い分けが基本になる。

独自ツールの追加も簡単だ。PydanticのBaseModelでパラメータを定義し、実行関数を書いてToolにまとめる。型ヒントとFieldの説明文が、そのままLLMへのツール定義（スキーマ）になる。

from pydantic import BaseModel, Field

from stirrup import Agent, Tool, ToolResult, ToolUseCountMetadata
from stirrup.clients.chat_completions_client import ChatCompletionsClient
from stirrup.tools import DEFAULT_TOOLS


class GreetParams(BaseModel):
    """greetツールのパラメータ。"""

    name: str = Field(description="挨拶する相手の名前")
    formal: bool = Field(default=False, description="丁寧な挨拶にするか")


def greet(params: GreetParams) -> ToolResult[ToolUseCountMetadata]:
    greeting = f"Good day, {params.name}." if params.formal else f"Hey {params.name}!"
    return ToolResult(
        content=greeting,
        metadata=ToolUseCountMetadata(),
    )


GREET_TOOL = Tool(
    name="greet",
    description="名前で相手に挨拶する",
    parameters=GreetParams,
    executor=greet,
)

# 標準ツールに独自ツールを足してAgentへ渡す
agent = Agent(
    client=ChatCompletionsClient(
        base_url="https://openrouter.ai/api/v1",
        model="anthropic/claude-sonnet-4.5",
    ),
    name="greeting_agent",
    tools=[*DEFAULT_TOOLS, GREET_TOOL],
)

JSON Schemaを手書きせず、Pythonの型定義がそのままツール仕様になるのが効いている。LLMはnameが文字列でformalが真偽値であることを型から理解する。

メモリ（コンテキスト管理）は、フレームワーク側が自動で面倒を見る。Stirrupはコンテキスト上限に近づくと自動でこれまでのやり取りを要約し、長い対話やマルチターンのタスクでもコンテキスト溢れを防ぐ。さらに外部ツールを増やしたいときはMCPクライアント機能で、MCPサーバが提供するツール群をそのまま取り込める。自前ツール（Pydantic）と外部ツール（MCP）を同じエージェントに同居させられるのが強みだ。

・自前で増やす——PydanticでToolを定義しtools=に追加
・外部から借りる——MCPクライアントでMCPサーバのツールを接続
・記憶の維持——コンテキスト自動要約で長いタスクでも破綻しにくい

モデル選択とベンチマーク連携

Stirrupの「モデルを選びやすい」設計は、開発元がベンチマーク運営者であることと地続きだ。接続方法は大きく2系統ある。

・ChatCompletionsClient——OpenAI互換APIを話せるバックエンドに接続。OpenRouter経由でClaude・GPT・各種モデルを、あるいはDeepseekのような互換APIを直接指定できる
・LiteLLMClient——stirrup[litellm]を入れて使う。Anthropic・Google・その他LiteLLMがサポートする全プロバイダをmodel_slugで統一的に指定できる

どちらもクライアントを差し替えるだけでモデルが切り替わるため、「タスクの難度に応じてモデルを使い分ける」運用が自然にできる。ここでArtificialAnalysisのベンチマークが効いてくる。同社のIntelligence Index・速度・価格の実測値を見れば、「このエージェントタスクはどのモデルが費用対効果で勝つか」を判断材料にできる。

「ベンチマークでモデルを選び、クライアント1行で差し替える」——この往復のしやすさが、Stirrupをベンチマーク企業が出す意味につながっている。

LangChain / CrewAI / OpenAI Agents SDK との比較

エージェントフレームワークは思想で選ぶ。Stirrupと主要な選択肢を、設計の方向性で並べる。

軸を一言で言えば、「制御を増やすか、減らすか」だ。LangGraphやCrewAIは開発者が実行構造を設計する（制御を増やす）思想で、複雑なワークフローや厳密な分岐に強い。Stirrupは逆に制御を減らし、モデルの判断に委ねる。OpenAI Agents SDKもStirrupと同じく軽量寄りだが、OpenAIのエコシステム（handoff/guardrailの規約）を前提にする点が異なる。

・Stirrupを選ぶべき場面——「単体のエージェントに、code_exec・web・独自ツールを持たせて自律的に動かしたい」。スキャフォールドを書かずに最短で立ち上げたい
・LangGraphを選ぶべき場面——分岐・再試行・人間承認のフローを厳密に図として設計・可視化したい
・CrewAIを選ぶべき場面——「リサーチ担当」「執筆担当」のような役割分担で複数エージェントを協調させたい

優劣ではなく適材適所だ。「まず1体のエージェントを最小コストで動かす」ならStirrup、「複雑なワークフローや多エージェント協調を組む」なら他フレームワーク、と切り分けるのが現実的だ。各フレームワークの中身はLangGraph入門・CrewAI入門で個別に解説している。

実運用での注意点

最小コードで動く手軽さの裏で、本番投入時に押さえるべき点がある。

・コード実行は必ず隔離する——code_execは任意のシェルコマンドを実行しうる。ローカル実行は手元検証に留め、本番ではDockerかE2Bサンドボックスを選ぶ。エージェントにホスト環境を直接触らせない
・max_turnsで暴走を止める——Agent(..., max_turns=15)のように上限ターン数を設定し、モデルがループに陥っても止まるようにする。自律性が高いぶん、停止条件は明示する
・APIキーと環境変数の管理——OPENROUTER_API_KEYやBRAVE_API_KEYをコードに直書きせず、環境変数やシークレットマネージャで渡す。エージェントの出力ディレクトリにシークレットが漏れない設計にする
・バージョン固定——v0.1系と若く、APIは変わりうる。本番ではバージョンをピン留めし、アップグレード時は挙動を再検証する
・コスト監視——自律エージェントはツール呼び出しとモデル推論を繰り返すため、長いタスクではトークン費用が膨らむ。metadataでツール使用回数を取れるので、コストの観測点として使う

よくある落とし穴

導入初期につまずきやすいポイントをまとめる。

・web_searchが動かない——web_fetchは動くのに検索が失敗する場合、BRAVE_API_KEYが未設定なことが多い。web検索だけ別途キーが要る点を見落としやすい
・OPENROUTER_API_KEY未設定——最小エージェントが起動しない最頻の原因。クライアントのbase_urlに合ったキーを環境変数で渡す
・同期コードで書いてしまう——StirrupのAPIは非同期だ。async with agent.session(...)とawait session.run(...)を使い、エントリポイントはasyncio.run(main())で回す。普通の関数呼び出しのつもりで書くと動かない
・オプション未インストール——LiteLLMClientを使うのにstirrup[litellm]を入れていない、Dockerサンドボックスを選んだのにstirrup[docker]が無い、といったケース。必要なextrasを[all]か個別指定で入れる
・制御を増やそうとして思想とぶつかる——「計画→実行→検証」のような固定フローを無理に組み込もうとすると、Stirrupの軽量思想と噛み合わない。厳密なワークフロー制御が要件ならLangGraph側を選ぶのが筋。Stirrupはモデルに委ねる設計だと割り切る
・出力ディレクトリの取り違え——成果物はsession(output_dir=...)で指定した場所に書かれる。指定を忘れると意図しない場所に出力されたり、複数実行で混ざったりする

落とし穴の多くは「非同期API」「必要なextras」「別途キー」の3点に集約される。最初の起動でつまずいたら、まずこの3つを確認すると早い。

FAQ（7問）

Q1. Stirrupは何が新しい？LangGraphやCrewAIとどう違う？
モデルに進め方を委ねる「軽量＋ベストプラクティス内蔵」が核だ。LangGraphはグラフで実行を明示設計、CrewAIは役割分担で複数エージェントを協調させる思想で、いずれも開発者が制御構造を組む。Stirrupは逆に制御を減らし、code_exec・web・コンテキスト要約といった基盤だけを用意して進め方はモデルに任せる。

Q2. 開発元のArtificialAnalysisとは？
各社LLMを知能指数・速度・価格で横断比較するベンチマークサイトの運営チームだ。モデルの実測値を最も観測してきた立場から、先行エージェントの効くパターンを抽出してフレーム化したのがStirrup。MITライセンスで全コードが公開・監査可能だ。

Q3. 最小構成だとどれくらいのコードで動く？
クライアントとAgentを作り、session()内でrun()にタスク文字列を渡すだけ。実質10行未満で動く。OPENROUTER_API_KEYをセットすれば起動し、web検索を使うときだけBRAVE_API_KEYが追加で必要になる。

Q4. 独自ツールは追加できる？
できる。PydanticのBaseModelでパラメータを定義し、実行関数をToolにまとめてtools=[*DEFAULT_TOOLS, MY_TOOL]で渡すだけだ。型と説明文がそのままLLMへのツール定義になる。MCPクライアントで外部MCPサーバのツール群も取り込める。

Q5. どのLLMに対応している？
OpenAI互換APIならChatCompletionsClientで接続でき、OpenRouterやDeepseekをそのまま使える。stirrup[litellm]＋LiteLLMClientを使えばAnthropic・Googleなどを統一的に扱え、モデルは1行で差し替えられる。

Q6. 本番業務で使っても安全？
code_execが任意コマンドを実行しうるため、Docker/E2Bでの隔離が前提だ。max_turnsで暴走を止め、シークレットを渡しすぎないこと。v0.1系と若くAPIが変わりうるため、本番ではバージョン固定が無難。

Q7. 日本語のタスク指示でも動く？
動く。run()に渡す文字列は日本語で問題なく、内部のLLMが理解して実行する。ただし複雑な要件は英語で書いたほうが正確に伝わる場面はあり、「説明は日本語、用語やパスは英語」の混在が扱いやすい。

参考リンク

・ArtificialAnalysis/Stirrup（GitHub 公式リポジトリ・README）: https://github.com/ArtificialAnalysis/Stirrup
・ArtificialAnalysis（LLMベンチマーク・公式サイト）: https://artificialanalysis.ai/
・LiteLLM Providers（対応プロバイダ一覧）: https://docs.litellm.ai/docs/providers