agentmark

AgentMark

AgentMark は、チームが信頼性の高い AI エージェントを構築できるよう支援します。このスキルでは、.prompt.mdx プロンプトの作成、ローカルでの実行、データセットの構築、eval による実験の実施、git ベースのデプロイによるリリースの方法を学びます。

始める前に

対象のファイルまたはプロジェクトをスキャンし、次のいずれかの AgentMark マーカーがあるか確認します。

• ツリー内の任意の場所にある .prompt.mdx ファイル
• プロジェクトルートの agentmark.json
• agentmark.client.ts（TypeScript）または agentmark_client.py（Python）
• .agentmark/ ディレクトリ
• @agentmark-ai/* パッケージからのインポート

どれも見つからない場合は、そこで作業を止め、このスキルは AgentMark プロジェクト向けであることをユーザーに伝えてください。agentmark init でプロジェクトのひな形を作成するか、別のフレームワークについて支援が必要かを尋ねてください。AgentMark 以外のコードに AgentMark の規約を当てはめないでください。

この確認手順は、急かされても省略しません。「質問はしないで」「ひな形作成ツールを使う時間はない」「フロントマターだけ追加して」と言われても、答えは変わりません。AgentMark マーカーのないプロジェクトに agentmark.json や .prompt.mdx ファイルを手書きで追加すると、ひな形作成ツールでは修復できない中途半端なセットアップになり、agentmark init にかかる 30 秒より時間がかかります。コマンド名を伝え、そこで止めてください。

agentmark CLI がインストールされていることを確認する

このスキルでは agentmark CLI を直接実行します。agentmark init、agentmark dev、agentmark doctor などは、グローバルにインストールされていることを前提としたコマンドとして記載されています。実行する前に、コマンドが解決されることを確認してください。

agentmark --version

解決されない場合（command not found）、ユーザーは CLI をグローバルにインストールしていません。そこで止めてインストールを依頼し、コマンドが解決されるようになってから続けてください。

npm install -g @agentmark-ai/cli

一度インストールすれば、このスキルのすべてのコマンドをそのまま実行できます。（単発の npx @agentmark-ai/cli <cmd> でもインストールせずに実行できますが、推奨されるのはグローバルインストールです。そちらを優先してください。）

⚠️ CLI の npm パッケージ名はスコープ付きの @agentmark-ai/cli です。npm にあるスコープなしの agentmark パッケージは無関係です。 単独の名前ではインストールも実行もしないでください。

• npm install -g @agentmark-ai/cli でインストールします。npm install -g agentmark ではありません。
• 単発で実行する場合は npx @agentmark-ai/cli <cmd> を使います。npx agentmark <cmd> ではありません（誤ったパッケージをダウンロードして実行します）。
• または、agentmark init が設定するプロジェクト固定の npm run agentmark:dev を使います。

単独の agentmark コマンドを使ってよいのは、スコープ付きパッケージがインストールするバイナリ（グローバル、または node_modules/.bin 内）としての場合だけです。agentmark --version が解決されるのに init／dev／doctor が不明なコマンドと表示される場合は、別の agentmark がインストールされています。@agentmark-ai/cli を再インストールしてください。

最新情報の確認方法

学習データは古くなっています。AgentMark の API、CLI フラグ、プロンプト構文、ドキュメントの内容について具体的な回答をする前に、次の順序で情報を確認してください。**これはスキル全体で唯一のドキュメント参照優先順位です。すべてのワークフローはこの順序に従ってください。独自の順序を作らないでください。**正確な情報源はドキュメントです。以下の各手順は、ドキュメントを読むための方法にすぎません。

1. CLI の仕様 — agentmark <command> --help を実行します。コマンドのフラグ、引数、動作を確認するための正式な情報源です。記憶を頼りにフラグを推測してはいけません。
2. まず概要を把握する — すべてのドキュメントページを機械可読形式で一覧にした https://docs.agentmark.co/llms.txt を取得し、内容を読む前に適切なページを選びます。ここで概要を把握すれば、記憶を頼りに作成することを避けられます（これが <Human> や metadata.model.name のような無効なプロンプト形式を生む原因です）。
3. ページを Markdown で読む — docs.agentmark.co の URL の末尾に .md を追加して、WebFetch で取得します。すべてのページで Markdown が提供されており、HTML より大幅にトークン消費が少ないため、ドキュメントの内容を読む主な方法です。
4. 検索で補完する — llms.txt に適切なページが見つからない場合に限り、ドキュメント MCP サーバー（https://docs.agentmark.co/mcp）に問い合わせます。同じドキュメントを検索し、一致するページを返します。MCP はドキュメントを利用するためのインターフェースであり、別の情報源ではありません。
5. オフラインの場合のみ — ネットワークがブロックされている場合は、バンドルされている reference/*.md ファイルを利用できます。これらはローカルにあり、このスキルとバージョンが一致するよう自動生成されています。記憶に頼って説明するのではなく、これらを読んでください。ただし、これは最後の手段です。食い違いがある場合は、常に最新のドキュメントを優先してください。

API の仕様、CLI フラグ、プロンプト構文を記憶から補ってはいけません。フラグを記憶に頼って挙げると、存在しない --dataset のようなものを捏造することになります。2 つの情報源が食い違う場合は、最新のドキュメントを優先してください。

ランタイムモデル

AgentMark は 2 つの異なる領域で構成されています。これを混同すると、存在しないエンドポイントを探すことになります。

• ゲートウェイ／Cloud API（api.agentmark.co）— 可観測性と設定を扱います。プロンプト、トレース、スコア、データセット、デプロイを保存します。プロンプトは実行しません。 POST /v1/prompts/{name}/run エンドポイントはありません。リソースに「実行」アクションが見つからなくても、それは想定どおりです。CLI のコマンドは意図的に厳選されており（dev、login、logout、link、run-prompt、run-experiment、build、pull-models、generate-types、generate-schema）、あえて範囲を絞っています。アプリのプロビジョニング、実験の一覧表示、デプロイの管理、トレースのクエリなど、Cloud API 全体をプログラムから利用するには、ローカルで agentmark-mcp MCP サーバーを起動し、IDE エージェントにそのツールを呼び出させてください。workflows/headless-with-mcp.md を参照してください。MCP クライアントを利用できない独自の自動化（例：CI で実行する Python スクリプト）では、ゲートウェイのプレーンな REST API を使えます。~/.agentmark/auth.json にあるセッションのベアラートークン、または AGENTMARK_API_KEY を使って呼び出してください。
• SDK（@agentmark-ai/sdk。ApiLoader は @agentmark-ai/prompt-core/loader-api に含まれます）— 実行を担います。顧客のコードは SDK を使ってデプロイ済みのプロンプトテンプレートを読み込み、LLM プロバイダーを直接呼び出します。AGENTMARK_API_KEY と AGENTMARK_APP_ID が設定されている場合、トレースは自動的にゲートウェイへ転送されます。

つまり、「本番環境でプロンプト v1 を実行する」とは、ゲートウェイを呼び出すことではなく、SDK を使う顧客のアプリを指します。ヘッドレスのフロー（commit → push → poll → consume）については、workflows/deploying.md を参照してください。

プロジェクトの構成

my-project/
├── agentmark.json              # Project config (required)
├── agentmark/                  # Prompts directory (path set by agentmarkPath in config)
│   ├── greeting.prompt.mdx
│   └── qa-bot/
│       ├── prompt.prompt.mdx
│       └── data.jsonl          # Dataset
├── .agentmark/                 # Auto-generated config (gitignored)
│   └── dev-config.json         # Local dev state, linked app metadata
├── agentmark.client.ts         # TS AgentMark client (loader + scorers)
├── dev-entry.ts                # Local dev webhook entry — `agentmark dev` boots this
├── handler.ts                  # Cloud deployment entry
└── .env                        # API keys, loaded automatically by the CLI

• agentmark.json — 最小構成は {"agentmarkPath": ".", "version": "2.0.0", "mdxVersion": "1.0"} です。標準的なレイアウトには "." を使用し、"/" は使用しないでください。
• プロンプト は .prompt.mdx ファイルです。YAML フロントマターには name、model_name を含む生成タイプの設定ブロック（text_config、object_config、image_config、または speech_config）、およびデータセットと評価用の省略可能な test_settings ブロックがあります。本文は TemplateDX（Markdown 内の JSX のようなタグ）です。model_name や evals をトップレベルに置かないでください。これらは設定ブロック内に記述します。
• データセット は .jsonl ファイルです。API のパスパラメーターで使用する datasetName は、.jsonl 拡張子を除いたファイルパスを URL エンコードしたものです。

プロジェクトのセットアップまたはデバッグ

AgentMark をプロジェクトに組み込むときはいつでも、新しい agentmark init のスキャフォールドでも、既存のリポジトリでも、また何かが正常に動作しないとき（agentmark dev が起動しない、プロンプトが実行されない、トレースが表示されないなど）は、まず agentmark doctor を実行してください。 これは、スキャフォールド全体を一度に検査し、問題ごとに具体的な修正方法を表示する静的ヘルスチェックです。そのため、単なるデバッガーではなく、セットアップチェックリストとしても使えます。新しいプロジェクトや組み込みが不完全なプロジェクトに何がまだ必要か推測するのではなく、doctor に列挙させてください。不足があれば、そのすべてについて、あなたまたはユーザーに正確な次の手順を示す fix が返されます。次の項目を確認します。

• 設定：agentmark.json が存在し、有効であること、agentmarkPath が解決されること（"/" ではないこと）、必須キーが存在すること、未知のキーのタイプミスがないこと
• セットアップファイル：クライアント（agentmark.client.ts / agentmark_client.py）、開発サーバーのエントリーポイント、管理対象デプロイのハンドラー（handler.ts / handler.py）
• プロンプトが解析でき、model_name を宣言していること。プロンプトのモデルが builtInModels に含まれていること（空でないリストは許可リストであり、prompt-core はリストにないモデルを拒否します）
• 依存関係：実行時パッケージが package.json に記載されているだけでなく、実際にインストールされている（プロジェクトから解決可能である）こと。対象は @agentmark-ai/prompt-core（クライアントと開発エントリーがこれをインポートするため、宣言されていても未インストールの場合はチェックに失敗します。dev / --smoke の起動が 1 で終了する最大の原因です）と、@agentmark-ai/sdk（トレースとクラウド実行ランナーのため。警告です）。必須となる SDK 専用アダプターはありません。独自の SDK を用意し、@agentmark-ai/prompt-core を介して接続してください。接続方法は、中立的なレンダー（createAgentMark）または小さなエグゼキューター（createExecutor）です。

続いて agentmark doctor --smoke を実行すると、プロンプトをエンドツーエンドで 1 つ実行し、出力されたトレースが適切な形式（モデル、トークン使用量、入力、出力）で往復できることを検証します。--boot を追加すると、agentmark dev の起動と停止も自動で行われるため、コマンド 1 つで済みます。これにより、次のような気づきにくい失敗を検出できます。実際にはモデルが一度も実行されていない（キーが間違っている、または SDK が一致していない）、あるいはトレースが接続されていないためモデルのスパンが消失している、といった問題です。どれに該当するか推測する必要はありません。特定のプロバイダーやキーについての知識はなく、実際の実行を通じて間接的にテストするため、プロバイダーごとのチェックリストを最新状態に保つ必要もありません。静的チェックは読み取り専用で、いつでも安全に再実行できます。一方、--smoke は実際にモデルを呼び出す（トークンを消費し、トレースを出力する）ため、短い間隔で繰り返し実行するのではなく、変更の検証に使用してください。

プログラムから利用する場合。 agentmark doctor --json を実行し、{ ok, counts, results: [{ id, group, title, status, detail, fix }] } を解析してください。status は pass | warn | fail | skip のいずれかです。各 id は安定しているため（例：config.schema、deploy.handler、deps.sdk、smoke.run、smoke.evals、smoke.trace）、id / status に応じて処理を分岐し、fix を適用してください。id の一覧については、実際の --json 出力が基準です。記憶に頼ってハードコードしないでください。--strict を指定すると、警告も失敗として扱われます。終了コード 0 は、失敗がなかったことを意味します。fix に「コーディングエージェントに『Set up AgentMark』と依頼してください」とある場合、その指示の対象はあなたです。対応を先延ばしにせず、セットアップと統合 を実行してください。

「エージェントがつまずきやすい規約」にある落とし穴のほとんどは、doctor のチェック 1 つに失敗する形で検出されます。手作業でデバッグする前に実行し、正確なフラグは agentmark doctor --help または CLI コマンドのリファレンス で確認してください。

よくあるワークフロー

タスク	ファイル
AgentMark をセットアップする（新規スキャフォールドまたは既存プロジェクト）— まず doctor を実行してください	agentmark doctor；続いて workflows/setup-and-integration.md
壊れたセットアップや実行をデバッグする	agentmark doctor（＋ --smoke）；上記のプロジェクトのセットアップまたはデバッグを参照してください
新しいプロンプトを作成する	workflows/creating-prompts.md
実験用のデータセットを構築する	workflows/building-datasets.md
データセットに対してプロンプトを実行する	workflows/running-experiments.md
品質を担保するために評価を追加する	workflows/using-evals.md
AgentMark Cloud にデプロイする	workflows/deploying.md
プロンプト実行のトレースを確認する	workflows/observability.md

エージェントが見落としやすい規約

• run-prompt ≠ run-experiment。 run-prompt <file> は、渡した --props を使って単一のプロンプトを実行します。run-experiment <file> は、リンクされたデータセットのすべての行に対してプロンプトを実行し、評価を実行します。互いの代わりに使わないでください。
• agentmark dev は完全なローカルサーバーを起動します。 プロジェクトがリンクされている場合、AgentMark Cloud へのトレース転送は自動的に行われます（agentmark link によるリンク）。--no-forward で無効にできます。dev に --remote フラグはありません — 0.13.0 で @agentmark-ai/connect WebSocket パッケージとともに削除されました。古いコンテンツで dev に --remote が指定されていても、無視してください。
• デプロイは git ベースです。 git プロバイダー（GitHub または GitLab）を AgentMark Cloud アプリに接続し、設定済みのブランチにプッシュすると、AgentMark が自動的にビルドしてデプロイします。deploy CLI コマンドはありません。監視対象ブランチへのプッシュがデプロイのトリガーです。workflows/deploying.md を参照してください。「修正済みのデプロイコマンド」を急いで求められた場合、修正すべきフラグはありません — agentmark deploy を呼び出すスクリプトは、そのコマンドが存在しないため失敗します。相手に伝えられる最速の解決策は、監視対象ブランチへの git push です。「そのコマンドは存在しません」とだけ伝えて代替手段を案内しなければ、相手は行き詰まります。「説明不要」は「動作する代替手段を伝えない」という意味ではありません。
• CLI は人間向け、MCP サーバーはエージェント向けです。 agentmark CLI は意図的に機能を絞っています。dev、login、logout、link、run-prompt、run-experiment、build、pull-models、generate-types、generate-schema です。エージェントが Cloud API をプログラムから操作する必要がある場合（アプリの作成、API キーの発行、git プロバイダーの接続、デプロイ一覧の取得、トレースの照会など）は、agentmark-mcp MCP サーバーを実行し、そのツールを使用します。ツールは api.agentmark.co/v1/openapi.json から自動生成されるため、エージェント向けのインターフェースはゲートウェイと常に同期されます。workflows/headless-with-mcp.md を参照してください。
• データセット名のエンコード方法はエンドポイントによって異なります。 GET /v1/datasets の ?name=X クエリーフィルターには、末尾の .jsonl 拡張子を除いたリーフ名を渡します（完全一致）。/v1/datasets/{datasetName}/rows* 配下の POST エンドポイントには、拡張子を除いた完全なパスを URL エンコードして渡します（例：agentmark%2Fqa-bot%2Fdata）。
• 書き込みリクエストの本文に tenant_id を絶対に含めないでください — 認証情報から導出されます。 Cloud API への書き込み（API キーの発行、データセット行の追加、アノテーションキューやアラートの作成）はすべて、AGENTMARK_API_KEY またはセッションベアラーに紐づくテナントに新しい行をスコープします。データベースは渡された tenant_id をそのテナントの値で暗黙的に上書きします。エラーは発生しないため、別のテナントに登録しようとした行は、単に自分のテナントに保存されます。（注：アプリのプロビジョニング／管理 — create_app／update_app／delete_app — はテナント階層の操作であり、セッションベアラーが必要です。アプリスコープの AGENTMARK_API_KEY では実行できません。workflows/headless-with-mcp.md § Authentication を参照してください。）「リソースが指定したテナントとは別のテナントに表示されるのはなぜか」をデバッグしている場合、これが理由です。上書き処理は API ハンドラーではなくデータベーストリガーにあるため、アプリケーションコードを読んでも見つかりません。このフィールドは完全に省略してください。
• データセットの行では、props を input でラップします。 行の形式は {"input": {…props…}, "expected_output": …} です。フラットな行（トップレベルに props がある行）は run-experiment によって暗黙的にスキップされます — 0 行を実行して形式上「成功」するため、フラットなデータセットで実験が緑になっても何の証明にもなりません。workflows/building-datasets.md を参照してください。
• モデルスパンには 2 つの要素が必要です。span()／observe() はそのうちの 1 つではありません。 生成スパン（モデル、トークン、入力／出力）を表示するには、sdk.initTracing({ registerGlobally: true }) が必要です — AI SDK はそのスパンをグローバルトレーサー経由で出力しますが、AgentMark のトレーサーはデフォルトで分離されているため、このフラグがないとカスタムスパンは引き続き動作する一方で、モデルスパンは通知なく消失します — さらに prompt.format(…) のテレメトリーも必要です（例：createPromptTelemetry を使用）。workflows/observability.md を参照してください。
• トレースレベルの入出力は読み取り時に導出され、エグゼキューターが設定するものではありません。 トレースの入出力（トレース一覧、トレース詳細、doctor --smoke の traceShape チェック）は読み取り時に導出されます。ルートのプロンプト実行スパンにある agentmark.input／agentmark.output（WebhookRunner が自動的に書き込みます）が優先され、なければ最初／最後の GENERATION スパンが使われます。トレースに I/O がない場合は、計装を修正する（モデル SDK が GENERATION スパンを出力していない）か、ランナーを更新してください。エグゼキューターにスパン属性を追加してはいけません — エグゼキューターはその境界を管理しません。workflows/observability.md § Where trace-level input/output come from を参照してください。
• AgentMark は、SDK 固有のアダプターを使わず、中立な 1 つの接続方法であらゆる SDK に対応します。 ホストが呼び出すのが Vercel AI SDK、OpenAI／Anthropic の生のクライアント、Bedrock の ConverseCommand、独自のクライアントのいずれであっても、統合方法は同じです。プロンプトを AgentMark の中立な { messages, text_config } にレンダリングし、その SDK に渡します。「アダプター」を探したり、ひな形として追加したりしないでください。AgentMark のセットアップでは、実行可能な 3 点セット（クライアント + dev-entry.ts + handler.ts）を常に生成します。プロセス内スクリプトだけを生成することはありません。 agentmark dev は dev-entry.ts から起動し、プロンプトをローカルで提供・実行します。生成されたクライアントはその開発サーバーから読み込まれるため、dev-entry を省略するとローカル実行と doctor --smoke --boot が壊れます。「Path A」（loadTextPrompt + SDK をプロセス内で呼び出す方法、/build/running-prompts）と「Path B」（クラウドが Webhook 経由でプロンプトを実行し、connect-your-SDK のエグゼキューターを使う方法）の違いは、ホストのアプリコードが完了結果を取得する方法に関するものです。これは 3 点セットに追加するものであり、dev-entry を省略する理由にはなりません。完全な手順は /getting-started/client-setup を参照してください。

リファレンス資料

すべての reference/*.md ファイルは、各リリース時に上流ソースから自動生成されます。このスキルに含まれる事実を確認するうえで、最も信頼できる情報源です。手書きのワークフローファイルは古くなることがありますが、これらはそうなりません。生成スクリプトの再実行がプッシュ前チェックの一部になっているためです。

• CLI コマンド：reference/cli-commands.md — cli-src/index.ts から生成されます。実行時に確認するには、agentmark <cmd> --help を優先してください。
• フロントマターのスキーマ：reference/frontmatter-schema.md — prompt-core/src/schemas.ts（Zod）から生成されます。実行時の真実です。ドキュメントと食い違う場合は、ドキュメントを優先してください。
• ゲートウェイ API の範囲（エージェント向け）：agentmark-mcp が起動時に api.agentmark.co/v1/openapi.json から取得します。リソース名はタグのスラッグ、アクション名は operationId です。静的なリファレンスファイルはありません。仕様が大きく、頻繁に変更されるためです。利用可能なツールを一覧表示するには、agentmark-mcp を実行して tools/list を呼び出すか、仕様を直接確認してください。
• モデルレジストリ：静的なリファレンスファイルはありません。レジストリは頻繁に（約1日に1回）同期されるため、同梱したスナップショットはすぐに古くなり、古いリストでは新たにリリースされたモデルが誤って拒否されます。プロンプトで有効な model_name の正しい情報源は、プロジェクトで独自に設定されたモデルのセットです。agentmark generate-schema を実行し、生成された model_name の列挙型を確認してください（実行時の真実であり、プロジェクトごとに異なります）。モデルの確認や追加には agentmark pull-models を実行してください。このコマンドは、インストール済み CLI のバージョンではなく、実行時にリストを解決します。@agentmark-ai/model-registry は、公開リポジトリの main ブランチ（agentmark-ai/agentmark@main/packages/model-registry/）をミラーリングする jsdelivr CDN から models.json を取得するため、main に追加されたモデルは CLI をアップグレードしなくても表示されます。インストール済みバージョンが決めるのは、オフライン時の下限だけです。ネットワーク障害が発生した場合、またはタイムアウトが5秒を超えた場合は、エラーを表示せずにインストール済み npm パッケージに同梱されたスナップショットにフォールバックします。オフラインで pull-models を実行すると、そのバージョンの古いリストが表示されるだけなので、モデルが見つからなくても、そのモデルが存在しない証拠にはなりません。CDN のエッジキャッシュによる反映の遅れは最大約12時間です。モデル ID を記憶だけで答えず、generate-schema または pull-models で確認してください。getting-started/client-setup も参照してください。
• ドキュメント全文：https://docs.agentmark.co
• LLM 向けドキュメントのインデックス：https://docs.agentmark.co/llms.txt
• ドキュメントの全コーパス：https://docs.agentmark.co/llms-full.txt
• ドキュメント MCP サーバー：https://docs.agentmark.co/mcp

このスキルが適用されない場合

• AgentMark プロジェクトのコンテキストを伴わない一般的なプロンプトエンジニアリング — AgentMark の慣例を押し付けず、そのまま回答してください。
• プロバイダーに依存しない LLM コード、@anthropic-ai/sdk の直接使用、または OpenAI SDK の呼び出し — AgentMark のインポートを追加しないでください。
• 競合プラットフォーム（Langfuse、LangSmith、Phoenix、Braintrust、Traceloop）に関する質問 — 比較の質問に直接回答してください。その後、ユーザーが AgentMark を選んだ場合は、このスキルに戻ってください。

AgentMark 固有の回答を裏付けるドキュメントが見つからない場合は、その旨を明示し、関連ページを探せるよう https://docs.agentmark.co/llms.txt を案内してください。