AIエージェントの全体像とCursor SDK

エージェント開発をやったことがなかったので、Cursor SDK で何か作ってみました

Transcript

1. Cursor Meetup Osaka #2 AIエージェントの全体像と Cursor SDK しまぶー
2. ・YouTubeやってます ・受託開発で暮らしてます ・スマブラとスプラが好きです しまぶー INTRODUCTION @shimabu_it
3. 1 イントロ
4. 1 — イントロ みなさん、 Cursor 使ってますか？
5. 1 — イントロ 「Cursor がメインです」という方？
6. 1 — イントロ Cursor SDK を使ったことある方？
7. 1 — イントロ 私も Cursor SDK を 使ったことがありません
8. 1 — イントロ 普段 AI エージェントを使って開発しているが AI エージェント自体の開発 をしたことはない
9. 1 — イントロ 登壇ネタにしよう ということで 調べたのでその記録を共有します
10. 2 AI エージェントの全体像
11. 2 — AIエージェントの全体像 AI エージェント開発って言っても そもそも何を開発すれば良いんだろう
12. 2 — AIエージェントの全体像 エージェントを構成する コンポーネントを 1つずつ見ていく
13. 2 — AIエージェントの全体像 / コンポーネント分類 必須 LLM 大量のテキストデータを学習して、人間のような言語を 理解・生成できる AIモデル。エージェントの頭脳。 ツール呼び出し 外部のツール（関数・ API・データベースなど）を呼び出して、 内部知識だけでは対応できないタスクを実行できるようにする仕組み。 推論ループ 「LLMが行動を決める →実行→結果を渡して再判断」を 完了まで繰り返すループ。
14. 2 — AIエージェントの全体像 / コンポーネント分類 実質必須 コンテキスト管理 LLMに毎回渡す入力を、上限内かつ判断精度が落ちない量に 収める取捨選択・加工 (要約・圧縮・古い結果の破棄 )。 プロンプト設計 システムプロンプト + ツール定義 (説明文・引数スキーマ ) + 出力フォーマット強制 (Structured Outputs)の3点セット。 オブザーバビリティ 各ステップの入出力・ツール呼び出し・トークン数を 記録・可視化する仕組み。デバッグの前提条件。 エラーハンドリング リトライ、フォールバック、レート制限対処などの 失敗時に処理を立て直すロジック群。
15. 2 — AIエージェントの全体像 / コンポーネント分類 本番運用段階 評価基盤 LLM-as-a-judge(別のLLMによる採点 )、A/Bテスト、 本番データからの評価セット構築。 ガードレール 入出力を機械的に検査しブロックする層。 プロンプトの外側で強制するのがポイント。 コスト・レイテンシ最適化 同じ品質をより安く・速く実現するための技術群。 プロンプトキャッシュ、モデルルーティング、並列化など。
16. 2 — AIエージェントの全体像 / コンポーネント分類 推奨 インジェクション対策 外部コンテンツ内に仕込まれた指示文を、 LLMが誤って実行する攻撃への対策。 ツールの権限設計 各ツールが操作できる範囲の定義。最小権限、読み取り /書き込みの分離、ス コープ限定。 Human-in-the-loop 危険な操作の直前で停止し人間の承認を待つ仕組み。 書き込み系操作があるならほぼ必須。 コスト・予算管理 支出上限の設定、使用量の可視化とアラート。 公開前にはほぼ必須。
17. 2 — AIエージェントの全体像 / コンポーネント分類 用途次第 サンドボックス 生成コードを隔離環境 (コンテナ等 )で実行する仕組み。 コード実行するなら無条件で必須。 RAG / ベクトルDB 独自知識を意味的類似度で検索してプロンプトに差し込む手法と その検索基盤。必要な場合のみ。 長期メモリ セッション終了後も残る記憶をファイル /DBに保存し、 次回注入する仕組み。コンテキスト管理の延長。 状態管理 / 永続化 進行状態を保存し中断・再開できるようにする仕組み。 長時間タスクや承認待ちがある場合に。
18. 2 — AIエージェントの全体像 どう考えても多すぎます
19. 2 — AIエージェントの全体像 しかも AI “コーディング ” エージェントなら 推奨・用途次第 もほぼ必須
20. 2 — AIエージェントの全体像 AI コーディングエージェントを作るのは とてつもなく難しい
21. 2 — AIエージェントの全体像 各コンポーネントを レイヤー分けしてみる
22. 2 — AIエージェントの全体像 ハーネスが関係する領域 広範囲をカバーしている
23. 2 — 気づき AI コーディングエージェントを作る ≒ ハーネスを作るということ
24. 2 — AIエージェントの全体像 Claude Fable 5 を使っても すべて自前開発は厳しい
25. 2 — 主要技術マップ サードパーティに頼ればいけるかも？
26. 2 — 主要技術マップ (1/5) モデルインターフェース層 コンポーネント 主要な選択肢 備考 LLM Composer / Claude / GPT / Gemini / DeepSeek / Kimi Composer-2.5が最高ですよ AIゲートウェイ （API統一・ルーティング） Vercel AI Gateway、Cloudflare AI Gateway、 OpenRouter、LiteLLM モデル差し替え・フォールバック・コスト記録 ツール定義・構造化出力 OpenAI Strict Mode、Anthropic output config、 Vercel AI SDK + Zod スキーマ→ツール定義の自動生成まで担う プロンプト設計 - フレームワークなどの流儀に合わせて設計
27. ※ エージェントフレームワーク（ LangGraph等）は単一のコンポーネントではなく、この層の 5コンポーネント全体をカバーすることが多い コンポーネント 主要な選択肢 備考 推論ループ Mastra（TS）、VoltAgent、Vercel AI SDK、LangGraph フレームワーク採用の最大の動機がここ。 ツール呼び出し制御 同上（フレームワーク内蔵）＋ MCPクライアント各実装 ほとんどの場合、フレームワークの範疇。 コンテキスト管理 フレームワーク内蔵機能（LangGraphのメッセージ管理、ハー ネスSDKの自動コンパクション等） 独立製品がほぼない領域。 状態管理・永続化 フレームワークのcheckpointer、Temporal、Inngest 長時間タスクやプロセス再起動を跨ぐ再開が 要件なら耐久実行基盤へ差し替え エラーハンドリング tenacity（Py）、p-retry（TS）、ゲートウェイ側機能 レート制限対処はゲートウェイに寄せるのが楽 2 — 主要技術マップ (2/5) オーケストレーション層
28. コンポーネント 主要な選択肢 備考 ツール接続の標準 MCP（Model Context Protocol） 主要フレームワークが対応済み。 サンドボックス （コード実行） E2B、Daytona、Modal、Vercel Sandbox、 Cloudflare Sandboxes コーディングエージェントでは実質必須。 RAG・ベクトルDB Pinecone、turbopuffer、Qdrant、pgvector TursoやMongoDBなどDBに付属する場合も。 長期メモリ Mem0、Zep、Letta CLAUDE.mdやAGENTS.mdのような 永続指示ファイルも含まれる。 2 — 主要技術マップ (3/5) ケイパビリティ層
29. 2 — 主要技術マップ (4/5) 安全・ガバナンス コンポーネント 主要な選択肢 備考 注入攻撃対策 Lakera Guard、LLM Guard（Protect AI） 検知だけでは不完全。ツール権限の最小化との併 用が前提 ツール権限設計 フレームワーク/SDKの権限設定（Claude Agent SDKの permissions、Codexのsandboxモード等） 製品というよりツール実装側の設計責務。読み取 り/書き込みの分離が基本 HITL LangGraphのinterrupt機構、HumanLayer、各SDKの Hooks（Cursor/Claude/Codex） 危険な操作（書き込み・実行・送信）の前に承認を 挟む制御点 ガードレール Guardrails AI、NVIDIA NeMo Guardrails、 Llama Guard、各社Moderation API 入出力の検証・禁止行動の防止。公開サービス化 の前に必須
30. 2 — 主要技術マップ (5/5) 運用・プラットフォーム コンポーネント 主要な選択肢 備考 オブザーバビリティ Langfuse(OSS・セルフホスト可)、LangSmith、Arize Phoenix、Braintrust、Datadog LLM Observability OpenTelemetryのGenAI規約準拠を選ぶとロック イン回避できる コスト・予算管理 LiteLLMの予算/クォータ機能、Portkey、Helicone AIゲートウェイ層に同居させるのが定石。SDK系 を使う場合はベンダーの課金ダッシュボード＋自 前の上限制御 評価基盤 promptfoo、DeepEval、Ragas、Braintrust、LangSmith Evals promptfooはCIに組み込みやすく、フェーズ1から の軽量評価に向く コスト最適化 プロバイダ純正のprompt caching、ゲートウェイのキャッ シュ/モデルルーティング 専用製品より既存レイヤー（ゲートウェイ・プロバイ ダ機能）で賄えることが多い
31. 2 — AIエージェントの全体像 これらを組み合わせて開発すれば ...
32. 複雑すぎる ...やりたくない ... 2 — AIエージェントの全体像
33. 2 — AIエージェントの全体像 何を言ってるんだ
34. 2 — AIエージェントの全体像 Cursor SDK があるじゃないか
35. Cursor SDK とは TypeScript からプログラム的に CursorのAIコーディングエージェントを 実行・管理するための公式 SDK
36. 2 — コーディングエージェントSDK Cursor SDK を使えば ほとんどの領域を任せられる
37. 2 — コーディングエージェントSDK それ以外の有名どころとしては Claude Agent SDK、Codex SDK などがある
38. Cursor SDK Claude Agent SDK Codex SDK 提供元 Anysphere Anthropic OpenAI モデル Composer 2.5 ほか Cursor IDEで使えるもの Claude 系 基本は GPT 系 料金 サブスク + 従量課金 6/15 からクレジット制に移行 サブスク + クレジット制 言語 TypeScript / Python TypeScript / Python TypeScript 実行環境 Local / Self-hosted / Cloud(CursorのVM) Local / Self-hosted Local / Self-hosted 2 — コーディングエージェントSDK 3つの SDK を比較
39. Cursor SDK Claude Agent SDK Codex SDK 提供元 Anysphere Anthropic OpenAI モデル Composer 2.5 ほか Cursor IDEで使えるもの Claude 系 GPT 系 料金 サブスク + 従量課金 6/15 からクレジット制に移行 サブスク + クレジット制 言語 TypeScript / Python TypeScript / Python TypeScript 実行環境 Local / Self-hosted / Cloud(CursorのVM) Local / Self-hosted Local / Self-hosted 2 — コーディングエージェントSDK 3つの SDK を比較
40. 2 — コーディングエージェントSDK Cursor SDK の勝ちとします
41. 2 — コーディングエージェントSDK ちなみに... OpenHands Software Agent SDK を提供 Cline 5月中旬に SDK を公開したばかり Pi 海外のタイムラインでよく見るコーディングエージェント。 SDK あり（pi.dev/docs/latest/sdk）
42. 3 Cursor SDK を使った製品デモ
43. 3 — デモ HTML, CSS, JSをアップロードするだけで CMS化できるプロダクト
44. DEMO
45. 3 — デモ
46. 3 — デモ CMS化候補の検出 ほんのちょっとした工夫 1. HTML→Astro、Astro→EmDash に 変換する部分では Cursor SDK 未使用。 2. Cursor SDK 無しでも最低限動くようになっている 3. “繰り返し要素は親要素単位で提案し、子での個別提案をするな ” というドメイン知識を入れただけで精度が爆上がりした
47. 3 — デモ MCPを通じてEmDashを操作 ほんのちょっとした工夫 1. EmDash化した後に MCPトークンを取得し、 それを send 時に挿入するようにしている。 2. CMS化候補の検出時は HTMLを渡して、それを元に検出させたが、 EmDash化したあとは、エージェント自身に調べさせている。 （エージェントがツールでアクセスできるなら、スナップショットを貼る必要 はないので）
48. 3 — デモ 今後 Web 制作の案件がきたら 秒で終わらせるために作り始めた
49. 3 — デモ しかし、この程度は Cursor SDKを使わずとも IDE でも簡単にできることに気づき、 急速にやる気が失われました 本当にありがとうございました。
50. 3 — 事例 Cursor SDK の事例は公式 Cookbook にもある • 最小限のスターターキット • Web アプリ形式のプロトタイピングツール • Cursor Cloud Agents を管理するための Kanban UI • ターミナルから Cursor エージェントを起動できる CLI • タスクを複数の AI エージェントに分担させ、進捗を Canvas で見える化するツール github.com/cursor/cookbook
51. 3 — 事例 Cursor SDK で作られたプロジェクトまとめ 1. エージェントがバグを見つけて証明する QA システム 2. Gmail / Google Chat に Cursor エージェントを埋込 3. 非エンジニア向けの Chrome 拡張機能 4. スクリーンショットから直接 Cursor エージェントを起動 5. Cursor SDK ベースの独自 CLI ツール 6. インタラクショントレースからコード全体を生成 7. CI エラーを自動修正する「 CI Autofix」 8. コミット時にドキュメントの陳腐化をチェック 9. EffectTS で Cursor SDK をラップしたライブラリ 10. 複数リポジトリを跨ぐエージェントオーケストレーター 11. 日記を作家風に変換し、振り返り質問をしてくれ ジャーナリングアプリ x.com/ericzakariasson/status/2049805277395095782
52. 3 — まとめ AI プロダクトを何か作ろうと思っている人は Cursor SDK をベースにアイディアを 考えてみると面白いかもしれません