Claude Agent SDKとMastraの違い — 完成したエージェントを借りるか、部品から組むか

違いは「どこまで出来上がったものを受け取るか」にある

Claude Agent SDKとMastraは、どちらもTypeScriptでエージェントを動かせます。ただ、最初に手渡されるものが違います。

Claude Agent SDKは、Claude Codeのツール・エージェントループ・コンテキスト管理をライブラリとして呼べるようにしたものです。ファイルの読み書きやコマンド実行は最初から入っていて、開発者は何を許可するかを決めます。

Mastraは、agent・workflow・memory・toolを部品として提供するTypeScriptのフレームワークです。モデルはprovider/model形式の文字列で選び、ファイル操作のような道具は自分でツールとして定義します。

「Claude Codeと同じ道具立てを自分のアプリに入れたい」ならAgent SDK、「自社のドメインに合わせてエージェントと手順を設計したい」ならMastraが入口になります。同じ軸でLangGraphやVercel AI SDKと比べた記事もあります。

Agent SDKは、Claude Codeのエージェントをそのまま呼ぶ

Agent SDKの概要ページは、Claude Codeのバイナリを動かすライブラリで、組み込みツール・権限・セッション・フックといったClaude Codeの機能が使えると説明しています。呼び出し側のコードは小さくなります。

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "テストが落ちている原因を調べて直して",
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

ここに「まずテストを走らせる、次にログを読む」という手順はありません。順序はClaudeがその場で決め、開発者が書いたのは使ってよいツールだけです。ループの中身はAgent SDKのエージェントループにまとめています。

認証には制約があります。概要ページによれば、事前の承認がない限り、第三者の開発者が自社製品でclaude.aiのログインやレート制限を提供することは認められていません。Agent SDKで作ったエージェントでも同じで、APIキーによる認証を使います。

自社製品に組み込む場合の表記にも決まりがあります。「Claude Agent」や「 Powered by Claude」は使えますが、「Claude Code」や「Claude Code Agent」という名前、Claude Codeを模したASCIIアートは認められていません。利用は、Anthropicの商用利用規約の対象です。

Mastraは、agent・workflow・memoryを部品として持つ

Mastraでは、まずツールをcreateTool()で定義します。id・description・inputSchema(zod)・execute()が揃った形です。次にAgentへid・name・instructions・modelとツールを渡し、Mastraインスタンスに登録します。

import { Agent } from "@mastra/core/agent";
 
export const supportAgent = new Agent({
  id: "support-agent",
  name: "Support Agent",
  instructions: "問い合わせ内容を調べ、根拠を添えて答えてください。",
  model: "anthropic/claude-sonnet-4-6", // provider/model 形式の文字列
  tools: { lookupOrderTool },
});

モデルはprovider/model形式の文字列で、Anthropicなら環境変数ANTHROPIC_API_KEYを読みます。上のclaude-sonnet-4-6は、Mastraの公式ページが既知のモデルIDとして挙げている例です。実際に使うIDは、Mastra側の対応モデル一覧で確かめてください。

始めるには、npm install @mastra/core@latest zod@latestなどで依存を入れ、package.jsonに"type": "module"を置きます。Node.js 22.18.0以降なら、TypeScriptのファイルを直接実行できます。

呼び出しはmastra.getAgentById()で取り出し、.generate()で完全な応答、.stream()でトークンの逐次配信を受け取ります。agentは、モデルが最終回答を出すか、任意の停止条件に達するまで反復します。

つまりMastraのagentは、ループ自体はフレームワークが回すものの、持たせる道具・指示・記憶・承認は開発者が部品として選ぶ設計です。

同じ「ツール1個」を書き比べる

どちらも、zodでスキーマを書いてツールを足します。違いは、渡し方です。

Agent SDKでは、tool()で定義したものをcreateSdkMcpServer()でインプロセスのMCPサーバーに包み、mcpServersで渡します。

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";
 
const lookupOrder = tool(
  "lookup_order",
  "注文IDから状態を返す",
  { orderId: z.string().describe("注文ID") },
  async (args) => ({
    content: [{ type: "text", text: `${args.orderId}: 発送済み` }],
  })
);
 
const orders = createSdkMcpServer({ name: "orders", version: "1.0.0", tools: [lookupOrder] });
 
for await (const m of query({
  prompt: "注文A-100の状態を教えて",
  options: { mcpServers: { orders }, allowedTools: ["mcp__orders__lookup_order"] },
})) { /* ... */ }

ツール名はmcp__<サーバー名>__<ツール名>になるため、allowedToolsにはmcp__orders__lookup_orderのように書きます。この名前の規則を知らないと、許可リストを書いても合わないことがあります。

Mastraでは、createTool()の結果をagentのtoolsにそのまま渡します。MCPサーバーを経由する必要はありません。

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const lookupOrderTool = createTool({
  id: "lookup-order",
  description: "注文IDから状態を返す",
  inputSchema: z.object({ orderId: z.string().describe("注文ID") }),
  outputSchema: z.object({ status: z.string() }),
  execute: async ({ orderId }) => ({ status: "発送済み" }),
});

Mastraの公式ページには、プレーンなオブジェクトでのツール定義は黙って実行されないため、必ずcreateTool()を使うという注意があります。executeの第1引数はinputSchemaで検証済みの入力、第2引数は実行コンテキストです。

Agent SDKのカスタムツールの作り方はAgent SDKカスタムツールで詳しく扱っています。

記憶と再開 — セッションかMemoryか

「会話の続きから再開できる」点は共通ですが、保存の単位が違います。

Agent SDKのセッションは、読んだファイルや分析結果を含む全文脈を復元します。ただし、保存されるのは会話であってファイルシステムではありません。ファイルの変更を戻したいなら、ファイルチェックポイントを別に使います。

Mastraは、記憶を層で選びます。メッセージ履歴だけならMemoryを渡すだけです。名前や好みのような構造化データを持たせるならWorking memory、過去の発言を意味で引くならSemantic recallです。長い会話では、古いメッセージを観察ログに圧縮するObservational Memoryも使えます。

注意点が一つあります。Mastraのメモリは、保存先(storage provider)が必須です。MastraインスタンスにLibSQLStoreのようなstorageを置かないと、履歴は永続化されません。

また、スレッドの所有者(resourceId)は作成後に変更できません。別のユーザーに同じスレッドIDを使い回すと、問い合わせ時にエラーになります。Agent SDKでユーザーごとに会話を分けるなら、ユーザーごとにセッションIDを管理する形です。

人の承認を挟むとき — 権限評価の流れか、ツール単位の停止か

承認の入れ方は、発想が逆です。

Agent SDKでは、すべてのツール呼び出しが同じ順で評価されます。フック、拒否ルール、確認ルール、権限モード、許可ルール、最後にcanUseToolコールバックです。コールバックは、前の段階で決まらなかった呼び出しだけを受け取ります。

options: {
  canUseTool: async (toolName, input) => {
    const ok = await askUser(`${toolName} を実行しますか`);
    return ok
      ? { behavior: "allow", updatedInput: input }
      : { behavior: "deny", message: "ユーザーが拒否しました" };
  },
}

落とし穴は、許可ルールやacceptEdits・bypassPermissionsで自動承認された呼び出しがcanUseToolに届かないことです。確認を必ず通したい検査は、先に走るPreToolUseフックに置きます。詳しくはAgent SDKのパーミッション制御とAgent SDKのHooksを参照してください。

Mastraでは、承認はツールの属性です。ツール定義にrequireApproval: trueを付けると、そのツールだけが実行前に止まります。ストリームにはtool-call-approvalのチャンクが流れ、approveToolCall()かdeclineToolCall()で続けます。

export const deleteRecordTool = createTool({
  id: "delete-record",
  description: "レコードを削除する",
  inputSchema: z.object({ id: z.string() }),
  resumeSchema: z.object({ approved: z.boolean() }),
  requireApproval: true,
  execute: async ({ id }) => ({ deleted: id }),
});

実行中に条件で止めたいなら、executeの中でsuspend()を呼ぶ方法もあります。承認の返事が再起動のあとに届く本番運用向けに、listSuspendedRuns()で保留中の実行を保存先から見つけ直せます。MCPサーバー単位のrequireToolApprovalもあります。

比べると、Agent SDKは「全呼び出しの評価順」を設計し、Mastraは「どのツールで止めるか」を設計します。ルールで広く縛るなら前者、止める場所が少数に決まっているなら後者が書きやすくなります。

手順を固定したいとき — Workflowが効く場面

Mastraには、agentとは別にWorkflowがあります。createStep()で入出力のスキーマ付きの段階を作り、createWorkflow()で.then()でつないで.commit()で確定します。

Mastraのドキュメントは、使い分けをはっきり書いています。手順が事前に分からない開放的な課題はagent、順序が決まった複数段階の処理はworkflowです。実行結果はsuccess・failed・suspendedなどの状態で返り、suspendedならresumeStreamで再開できます。

Agent SDKの概要ページのCapabilities表に、Workflowに当たる機能は挙がっていません。順序を固めたいときは、サブエージェントに役割を分けたり、フックで要所を検査したりして、ループの外側と周りを固めます。

承認待ちを含む多段の業務フロー(受付、調査、承認、実行)を決まった順で何度も回すなら、Mastraが自然です。「このリポジトリのバグを調べて直して」のように、道筋を決めずに任せたいなら、Agent SDKの得意領域です。

併用するなら、MCPでつなぐ

どちらかを選ぶ話に見えますが、MCPが接点になります。

MastraにはMCPServerがあり、agent・tool・workflowをStreamable HTTPのMCPサーバーとして公開できます。Agent SDKは、mcpServersにtype: "http"でリモートのMCPサーバーを渡せます。つまり、業務ロジックをMastra側に置き、コード編集のような作業をAgent SDKのエージェントに任せる構成が、MCPを介して成立します。

options: {
  mcpServers: {
    biz: { type: "http", url: "https://example.com/api/mcp/my-mcp-server/mcp" },
  },
  allowedTools: ["mcp__biz__*"],
}

URLは、Mastra側が/api/mcp/:serverId/mcpで配信するという記述から組み立てた例です。認証が必要なHTTPサーバーには、Mastra側でOAuth保護を設定し、Agent SDK側ではheadersで認証情報を渡します。接続の基本はAgent SDK MCP接続ガイドにあります。

選び方の早見表

Agent SDKの概要ページのCapabilities表は、モデルプロバイダーを切り替える機能を挙げていません。複数のプロバイダーを前提にするなら、この点が分かれ目になります。逆に、Claude Codeの道具立てそのものを求めるなら、Mastraでは、ファイル操作などのツールを自分で定義する作業が増えます。

まとめ

この2つは競合というより、守備範囲が違います。Agent SDKは「Claude Codeのエージェント」という完成品を借りる選択で、Mastraは「エージェントの部品」を組む選択です。

迷ったときは、先に承認の形を決めてください。全呼び出しを規則で縛りたいならAgent SDK、数個のツールだけ止めたいならMastraが書きやすくなります。決まった順序の業務フローが中心になるなら、Workflowを持つMastraから入る形が合います。