edgeone-makers-agents

EdgeOne Makers エージェント開発ガイド

⛔ プレビュー禁止：開発が完了したら、必ず edgeone makers dev で開発サーバーを起動し、present_files を使って http://127.0.0.1:8088/ を開いてプレビューしてください。file:// プロトコルで HTML ファイルを開いてはいけません（IDE が自動的に開いた場合も無視してください）。また、python -m http.server や npx serve などのセルフホストサーバーは使わないでください。Next.js プロジェクトでは、next.config に allowedDevOrigins: ["127.0.0.1"] も設定してください。

EdgeOne Makers 上で、本番環境に対応した AI エージェントのエンドポイントを構築します。5 つのフレームワーク用ルート、プラットフォームが注入するランタイム、ファイルベースのルーティングを利用します。

このスキルでは、EdgeOne Makers で AI エージェントのエンドポイントを構築するために、5 つのサポート対象フレームワーク（DeepAgents、LangGraph、CrewAI、OpenAI Agents SDK、Claude Agent SDK）を扱います。

このスキルを使う場面

• EdgeOne Makers で新しい AI エージェントのエンドポイントを作成するとき
• DeepAgents ／ LangGraph ／ CrewAI ／ OpenAI Agents SDK ／ Claude Agent SDK を Makers プロジェクトに接続するとき
• 既存のエージェントテンプレートをプラットフォームの禁止事項に照らしてレビューするとき
• 中断に対応した SSE ストリーミングを実装するとき
• context.store を使って会話状態を永続化するとき（LangGraph のチェックポインター ／ OpenAI のセッション ／ Claude のセッション ／ 会話スコープの state ／ claudeSessionBinding）
• context.sandbox ／ context.tools を使ってサンドボックスまたはプラットフォームのツールを呼び出すとき
• AI 推論（agents/）とデータの CRUD（cloud-functions/）を分離するとき

関連ドキュメント：コードで context.store または KV API を使う場合は、../makers-storage/SKILL.md も読んでください。

以下には使用しないでください：

• 通常の Edge Functions ／ Cloud Functions ／ Middleware → edgeone-pages-dev を使用してください
• デプロイのワークフロー → edgeone-pages-deploy を使用してください
• EdgeOne Makers プロジェクト以外での汎用 AI フレームワーク開発
• その他のプラットフォーム（Cloudflare Workers AI、Vercel AI SDK、AWS Bedrock）

このスキルの使い方（コーディングエージェント向け）

1. 以下の基本モデルに目を通します。Makers は汎用 API ルートとは異なります
2. 決定ツリーをたどり、5 つのフレームワーク用ルートから 1 つを選びます
3. 該当する references/*-route.md を読み、コピーして使えるスケルトンを確認します
4. 12 の禁止事項に照らしてセルフチェックします
5. 作業完了とする前に、references/review-checklist.md に沿って確認します

⛔ 重要なルール（必ず守ってください）

1. ファイルベースのルーティングは自動です。 agents/<name>/index.ts または agents/<name>.ts は POST /<name> になります。.edgeone/agent-node/config.json を手動で編集しないでください。
2. エントリのシグネチャは固定です。 TS: export async function onRequest(context: any)。Python: async def handler(ctx):。TS ではメソッド固有のバリアント（onRequestPost、onRequestGet など）も使用できます。
3. 環境変数は context.env 経由で読み取り、process.env / os.environ は決して使用しないでください。 これは agents/ および cloud-functions/ 内での読み取りと変更の両方に適用されます。フロントエンドコード（app/、src/）は影響を受けません。
4. ヘッダーはプレーンオブジェクトであり、Web の Headers API ではありません。 context.request.headers['x-custom-header'] を使用し、.get('x') は決して使用しないでください。
5. 会話 ID の契約。 AI エンドポイント（/chat、/outline など）は、フロントエンドから makers-conversation-id HTTP ヘッダーを受け取る必要があります。/stop エンドポイントは、リクエストボディに conversation_id を受け取り、キャンセルする実行中の会話を識別します。
6. モデル名 / ベース URL / API キーをハードコードしないでください。 context.env から AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL（+ オプションの AI_GATEWAY_MODEL）を読み取ってください。テンプレートで context.tools.web_search を使用する場合は、WSA_API_KEY（Tencent Cloud WSAPI）も設定してください。
7. SSE プロトコルは推奨される規約です（ランタイムによって強制されません）。 ランタイムは生のチャンクを転送するだけであり、SSE の内容を解析または検証しません。推奨されるイベントタイプは次のとおりです: ai_response / tool_call / tool_result / usage / suggest_actions / file_output / ping / error_message。ストリームは data: [DONE]\n\n で終了します。すべてのフレームワークは、フロントエンドの一貫性のためにこれに従うべきです。
8. ハートビートとバッファリング制御は必須です。 5 秒ごとに ping イベントを送信してください。レスポンスヘッダーには X-Accel-Buffering: no、Cache-Control: no-cache、Connection: keep-alive を含める必要があります。
9. 常に context.request.signal を尊重してください。 ループ内で signal?.aborted（TS）または signal.is_set()（Python）をチェックし、中断時には例外をスローせず、正常に終了してください。
10. ループに上限を設けてください。 手動の bind-tools ループはハードターン制限（例: for (let i = 0; i < 4; i++)）を使用します。SDK ルートは maxTurns を設定します。「モデルが停止と言うまで」の無制限ループは禁止です。
11. エラーでストリームをクラッシュさせてはいけません。 すべてのモデル / ツール呼び出しを try/catch でラップしてください。AbortError は静かに握りつぶしてください。その他のエラーは error_message イベントとして送出し、ストリームを途中で終了させないでください。
12. 適切な store エントリポイントを選択してください — それらは形状が等価ではありません**。**
    • context.store（エージェントエンドポイント、agents/<name>/）: 完全な AgentMemory。すべてのアダプター（openaiSession、claudeSessionStore、langgraphCheckpointer、langgraphStore、会話 state、claudeSessionBinding）を含みます。
    • context.agent.store（cloud-function エンドポイント、cloud-functions/<name>/）: ランタイムが langgraphCheckpointer と langgraphStore を除去します。利用できるのは汎用メッセージ API + openaiSession + claudeSessionStore（+ state / claudeSessionBinding）のみです。
    • 結果: langgraphStore.get/put を必要とするエンドポイントは、必ず agents/ 配下に置く必要があります。cloud-functions/ に置くと、実行時に kv.get is not a function がスローされます。
    • store?.langgraphStore ?? store を偽のフォールバックとして記述しないでください — cloud-function コンテキストでは、これはストア自体にフォールバックし、.get を持たないためクラッシュします。
13. 注入された context.sandbox / context.tools を使用してください。 /v1/sandbox/* 呼び出しを手書きしたり、トークンを解析したりしないでください。context.tools の形状は edgeone.json の agents.framework（claude-agent-sdk / openai-agents-sdk / langgraph / crewai / deepagents — basic は存在しません）によって決まります。context.tools.all()、.get(name)、.files()、.browser() を使用してください。Sandbox: sandbox.runCode(...) はトップレベルです（code_interpreter.runCode ではありません）。screenshot({ fullPage: true }) はブール値ではなくオブジェクトを受け取ります。タイムアウトは秒単位です。

注：赤い行番号が意図的に12から13へ飛んでいます。元のルール数は12で、#12ではサブ項目を追加してストアの形状に関する修正を取り込み、#13では他のルールと範囲をそろえるためにサンドボックス／ツールに関する項目を追加しました。

---

メンタルモデル

EdgeOne Makers Agent は汎用的なAPIルートのパターンではありません（Vercel AI SDK の route.ts でも、Express でもありません）。独自のランタイム規約があります。

項目	EdgeOne Makers の規約	⚠️ よくある間違い
バックエンドのエントリーポイント	agents/<name>/index.ts または agents/<name>.ts（Python：.py）	❌ app/api/<name>/route.ts ではありません
関数シグネチャ	export async function onRequest(context)（Python：async def handler(context)）	❌ export async function POST(req) ではありません
リクエスト本文	context.request.body（すでに解析済み）	❌ await req.json() ではありません
リクエストヘッダー	context.request.headers['x-foo']（プレーンなオブジェクト）	❌ headers.get('x-foo') ではありません（警告なしに undefined を返します）
環境変数	context.env.AI_GATEWAY_API_KEY（ランタイムから注入）	❌ process.env.X／os.environ ではありません（agents/ および cloud-functions/ では禁止）
モデルへのアクセス	context.env.AI_GATEWAY_* → Makers AI Gateway	❌ OpenAI／Anthropic への直接アクセス ではありません
プラットフォーム機能	ランタイムから注入される context.tools／context.sandbox／context.store	❌ 自分で SDK をインポート しません
ルート登録	ビルド時に自動スキャン → .edgeone/agent-node/config.json	❌ このファイルを手動で書かないでください

基本的な考え方：EdgeOne Agent Node Runtime（または Python Runtime）内で実行される薄いハンドラーを記述します。プラットフォームは context を通じて、モデルゲートウェイ、サンドボックス、ツール、セッションストアを注入します。コードは薄く保ち、ランタイムを活用してください。

---

標準的なプロジェクト構成

<template-name>-edgeone/
├── agents/                          # ⭐ Agent backend (core)
│   ├── _shared.ts                   # Shared: logger + SSE helper
│   ├── _model.ts                    # Shared: model name + Gateway env mapping
│   ├── <action>.ts                  # Simple agent: single file → POST /<action>
│   └── <action>/                    # Complex agent: directory form
│       ├── index.ts                 # onRequest entry → POST /<action>
│       ├── _skills.ts               # System prompt builder (optional)
│       ├── _tools.ts                # Custom / MCP tool definitions (optional)
│       └── _templates.ts            # Output templates / default data (optional)
├── app/ or src/                         # Frontend (any framework: Next.js, Vite, plain HTML, etc.)
│   ├── layout.tsx
│   ├── page.tsx
│   ├── globals.css
│   ├── components/
│   └── lib/                         # Frontend utils (context, hooks, conversation-id)
├── lib/                             # Cross-cutting utils (i18n, helpers)
├── cloud-functions/                 # ⭐ Data persistence functions (separate from agents)
│   ├── _logger.ts
│   └── <resource>/index.ts          # e.g. articles/, preferences/, history/, health/
├── .edgeone/
│   └── project.json                 # { Name, ProjectId }
├── edgeone.json                     # Deployment config + agents.framework
├── .env.example                     # ⚠️ MUST exist: declares AI_GATEWAY_API_KEY= and AI_GATEWAY_BASE_URL=
├── package.json                     # TS routes (A/B/C/D)
├── requirements.txt                 # ⭐ Python route (E) only
└── README.md

構成の原則

• agents/ = AI 推論：モデル呼び出し、ストリーミング、ツール呼び出しを行います。各ファイル／ディレクトリが1つの SSE エンドポイントになります。
• cloud-functions/ = データの CRUD：KV／Blob の読み書き、ヘルスチェック、履歴を扱います。JSON を返し、ストリーミングは行いません。
• _ で始まるファイル = 内部モジュール：ルートにはならず、兄弟ファイルからのみインポートされます。
• _shared.ts、_model.ts、_tools.ts は内部モジュールです。index.ts、create.ts はエンドポイントです。
• テンプレートごとに TS または Python を選択してください。1つのプロジェクト内で混在させないでください。

---

edgeone.json の設定

edgeone.json ファイルは、EdgeOne Makers プロジェクトのデプロイ設定ファイルです。ビルドコマンド、出力ディレクトリ、エージェント固有の設定を定義します。

主なフィールド

フィールド	型	説明
buildCommand	string	ビルドコマンド（例：npm run build）
outputDirectory	string	ビルド出力ディレクトリ（例：.next、dist、build）
framework	string	フロントエンドフレームワーク（例：nextjs、vite、react）
cloudFunctions	object	Cloud Functions の設定
agents	object	エージェント固有の設定（重要！）

agents.framework — コンソールのアイコン表示

edgeone.json の agents.framework フィールドは、EdgeOne Makers コンソールに表示するプロジェクトのアイコンを指定します。コンソールに正しいフレームワークのアイコンを表示するには、この設定が必要です。

使用できる値：

値	フレームワーク	コンソールのアイコン
claude-agent-sdk	Claude Agent SDK	Claude
openai-agents-sdk	OpenAI Agents SDK	OpenAI
langgraph	LangGraph／DeepAgents	LangGraph
crewai	CrewAI	CrewAI
deepagents	DeepAgents	DeepAgents

⚠️ 重要：agents.framework が設定されていない場合、または認識されない値が設定されている場合、コンソールには汎用アイコンが表示されます（フレームワーク固有のアイコンではありません）。

edgeone.json の例

{
  "buildCommand": "npm run build",  // your frontend build command
  "outputDirectory": "dist",
  "cloudFunctions": {
    "nodejs": {
      "includeFiles": []
    }
  },
  "agents": {
    "framework": "claude-agent-sdk"
  }
}

---

技術選択の判断ツリー

5つのフレームワークルートから1つを選択してください。

Need a sandbox to run code, process uploaded files, or use MCP tools?
├─ Yes → Claude Agent SDK
└─ No ↓
   Need multi-agent handoff?
   ├─ Yes → OpenAI Agents SDK
   └─ No ↓
      Need fine-grained graph control (nodes, edges, human-in-the-loop)?
      ├─ Yes → LangGraph
      └─ No ↓
         Want multi-agent role split (Sequential/Hierarchical)?
         ├─ Yes → CrewAI (Python only)
         └─ No → DeepAgents (simplest, auto context compression)

フレームワークの比較

フレームワーク	ランタイム	最適な用途
DeepAgents	Node + Python	シンプルなエージェントタスク、自動コンテキスト圧縮、サブエージェントのオーケストレーション
LangGraph	Node + Python	きめ細かなグラフ制御、ヒューマン・イン・ザ・ループ、永続的なスレッド状態
Claude Agent SDK	Node + Python	サンドボックスでのコード実行、ファイル処理、MCP ツール、セッションメモリ
OpenAI Agents SDK	Node + Python	マルチエージェントの引き継ぎ、ガードレール、セッションへの自動プリペンド
CrewAI	Python only	マルチエージェントの役割分担（順次／階層型）、組み込みのスキル／event_bus

---

ルーティング

トピック	参照先
Node エントリ（onRequest、context、AbortSignal）	platform/node-entry.md
Python エントリ（handler、ctx、asyncio.Event）	platform/python-entry.md
環境変数とモデルの規約	platform/env-and-model.md
SSE ストリーミングプロトコル	platform/sse-protocol.md
conversation-id のデュアルチャネルとフロントエンド	platform/conversation-id.md
agents/ と cloud-functions/ の分離	platform/cloud-functions.md
ストア（context.store）	capabilities/store.md
サンドボックス（context.sandbox）	capabilities/sandbox.md
ツール（context.tools）	capabilities/tools.md
Claude Agent SDK（Node）	node-frameworks/claude-sdk.md
OpenAI Agents SDK（Node）	node-frameworks/openai-agents.md
LangGraph（Node）	node-frameworks/langgraph.md
DeepAgents（Node）	node-frameworks/deepagents.md
Claude Agent SDK（Python）	python-frameworks/claude-sdk.md
OpenAI Agents SDK（Python）	python-frameworks/openai-agents.md
LangGraph（Python）	python-frameworks/langgraph.md
DeepAgents（Python）	python-frameworks/deepagents.md
CrewAI（Python のみ）	python-frameworks/crewai.md
レビューチェックリスト	review-checklist.md

---

環境のセットアップ

EdgeOne CLI をインストールする

npm install -g edgeone

確認します：edgeone -v。

環境変数を設定する

makers init、makers dev、makers link、makers env pull など、すべての edgeone CLI コマンドを実行する前に、次の環境変数を設定します。

export PAGES_SOURCE=skills

または、各コマンドの先頭にインラインで指定します。

PAGES_SOURCE=skills edgeone makers dev

これにより、コマンドが AI スキルのコンテキストから実行されたことをプラットフォームに伝えます。

ローカル開発

# 1. Link to remote project (pulls project ID + env vars)
PAGES_SOURCE=skills edgeone makers link

# 2. Pull remote environment variables to local .env
PAGES_SOURCE=skills edgeone makers env pull

デプロイ用の環境変数

⛔ 必ず .env.example ファイルを作成してください：CLI はこのファイルを使って、自動注入する変数を判断します。プロジェクトに .env.example がない場合、または AI_GATEWAY_* が宣言されていない場合、デプロイ後に環境変数が注入されず、API キーが不足してエージェントが実行時にエラーになります。

AI Gateway 変数（AI_GATEWAY_API_KEY、AI_GATEWAY_BASE_URL）は、デプロイ時に CLI によって自動的にプロビジョニングされます。.env.example で宣言していれば、手動での設定は不要です。

# .env.example (MUST be committed to the repo)
AI_GATEWAY_API_KEY=
AI_GATEWAY_BASE_URL=

CLI はこれらの宣言を検出し、デプロイ時に値を自動取得して注入します。

ユーザー定義のビジネス変数は、デプロイ前に手動で設定する必要があります。

# Set a variable on the remote project
edgeone makers env set MY_SECRET_KEY "my-value"

# List current variables
edgeone makers env ls

# Pull remote variables to local .env (for dev)
edgeone makers env pull

エージェントプロジェクトでよく設定する変数：

変数	必要な場合	設定方法
AI_GATEWAY_API_KEY	常に	CLI によって自動プロビジョニング
AI_GATEWAY_BASE_URL	常に	CLI によって自動プロビジョニング
WSA_API_KEY	web_search ツールを使用する場合	edgeone makers env set WSA_API_KEY <value>
カスタムのビジネスキー	プロジェクトごと	edgeone makers env set <KEY> <VALUE>

⚠️ エージェントプロジェクトをデプロイする前に、必要な環境変数がすべて自動プロビジョニング（AI_GATEWAY_*）されているか、edgeone makers env set で手動設定されていることを確認してください。変数が不足していると、実行時に 500 エラーが発生します。

---

標準作業手順

レビュアー向け標準作業手順

1. find . -type d -name agents -o -name cloud-functions を実行し、ディレクトリ構成を確認します。
2. edgeone.json を開き、agents.framework を読んでルートを特定します。
3. references/review-checklist.md のセクション A から順に確認します。
4. 違反を見つけた場合は、該当する Critical Rule とチェックリスト末尾の「修正表」を引用します。
5. 発生頻度が高い問題から、以下の順に確認します（観測された頻度順）：
   1. ❌ エージェント内での process.env.X / os.environ の使用（context.env を使用）。変更も違反です：process.env.X = '...' も違反です。
   2. ❌ headers.get('x')（headers['x'] を使用）
   3. ❌ 手動管理されている .edgeone/agent-node/config.json（削除してください）。⚠️ 判定方法：.gitignore に .edgeone が含まれているか確認します。含まれている場合 → ローカルの config.json はビルド成果物であり、違反ではありません。含まれていない場合 → .edgeone/ 全体がコミットされていることが違反です。
   4. ❌ sandbox.code_interpreter.runCode(...) の記述（トップレベルの sandbox.runCode(...) を使用）。screenshot(true) は screenshot({ fullPage: true }) にします。
   5. ❌ /stop に makers-conversation-id ヘッダーを付与（本文のみを使用）
   6. ❌ AI エンドポイントへのフロントエンドの fetch に makers-conversation-id ヘッダーがない
   7. ❌ edgeone.json に agents.framework がない（デフォルトの 'claude-agent-sdk' が実際のフレームワークと一致しない可能性があり、context.tools の形式に問題が生じます）

開発者向け標準作業手順

1. 上記の決定ツリーを使ってフレームワークを選びます。
2. 該当するフレームワークのリファレンスドキュメントからスケルトンをコピーします。
3. edgeone.json を設定し、agents.framework に正しい値を指定します。
4. フロントエンドで getOrCreateConversationId を使用し、makers-conversation-id ヘッダーを付けて fetch します。
5. 起動を確認し、Critical Rules に照らして自己チェックしたうえで、references/review-checklist.md に沿って確認します。

デプロイ前のSOP（⚠️ edgeone makers deploy の前に必ず実行してください）

このセクションは重要です。 AI エージェントは、ユーザーのデプロイを支援する際に、必ず以下の手順に従ってください。これらを省略すると、本番環境で実行時に500エラーが発生します。

1. プロジェクト内の環境変数をスキャンします：

   • .env、.env.example、.env.local を確認し、宣言されているすべての変数を調べます
   • ソースコードで context.env.XXX / ctx.env.get("XXX") の参照を検索し、必要な変数を特定します
   • よくあるパターン：SUPABASE_URL、SUPABASE_KEY、DATABASE_URL、WSA_API_KEY、カスタム API キーなど

2. 変数を分類します：

   • AI_GATEWAY_API_KEY + AI_GATEWAY_BASE_URL → 自動設定（.env.example で宣言されていれば対応不要です）
   • その他すべての変数 → 手動でアップロードする必要があります

3. 自動設定されない変数をアップロードします：

   # For each variable the project needs:
   edgeone makers env set <KEY> "<VALUE>"
   

   ユーザーから値が提供されていない場合は、デプロイ前にユーザーに確認してください。必要な変数がすべて設定されていることを確認せずにデプロイしてはいけません。

4. 確認します（任意ですが推奨）：

   edgeone makers env ls
   

5. デプロイします：

   edgeone makers deploy
   

Supabase を使用するプロジェクトをデプロイする際のやり取り例：

このプロジェクトでは、以下の環境変数を使用しています：

• AI_GATEWAY_API_KEY — 自動設定済み ✓
• AI_GATEWAY_BASE_URL — 自動設定済み ✓
• SUPABASE_URL — 手動設定が必要
• SUPABASE_ANON_KEY — 手動設定が必要

SUPABASE_URL と SUPABASE_ANON_KEY の値を提供してください。デプロイ前に設定します。

---