Agentty/ドキュメント

マニフェスト リファレンス

agentty-plugin.json のすべてのフィールド — 識別情報、実行方法、権限、パネル、コマンド、アイコン。

agentty-plugin.json はプラグインフォルダの直下に置かれ、そのプラグインが何であり、どう起動し、何ができ、インターフェースに何を加えるかを Agentty に伝えます。

json
{
  "id": "hello",
  "name": "Hello",
  "version": "0.1.0",
  "main": "main.mjs",
  "runtime": "node",
  "apiVersion": 1,
  "description": "Turns the current folder into a prompt.",
  "publisher": "you",
  "homepage": "https://example.com/hello",
  "agents": ["claude", "codex"],
  "permissions": ["prompt.inject"],
  "contributes": {
    "panel": { "title": "Hello", "icon": "sparkles" },
    "commands": [
      { "id": "hello.explain", "title": "Hello: Explain this folder", "icon": "bot" }
    ]
  }
}

識別情報#

フィールド必須説明
idはいa-z、0-9、- からなる 2〜40 文字。フォルダ名と一致させてください。
nameはいストアとパネルボタンに表示
versionはいmajor.minor.patch
descriptionストアカードの 1 行説明
publisher作者
homepagehttps:// である必要があります
keywordsストア検索用
linksカードにボタンとして出る { "label", "url" } を最大 6 件(プロジェクトサイト、ドキュメント、ソース)
icon下記一覧のアイコン名
logoプラグインフォルダ内の画像ファイル。icon の代わりに描画されます。モジュールはロゴをモジュール内に持ちます — ロゴを参照
agentsプラグインが動作する AI エージェント: ["claude"]、["codex"] または ["claude", "codex"]。省略すると Claude Code。カードに利用できる AIとして表示されます

実行#

フィールド既定値説明
main必須プラグインフォルダからの相対パスのエントリポイント
runtimenodenode(ログインシェル PATH の Node.js 18+)、python(python3 <main>)、executable(<main> を直接実行)、または wasm — <main> が Agentty 自身の実行する WebAssembly モジュール。Rust と WebAssembly を参照
apiVersion1作成時に基準としたプラグイン API のバージョン。2 は AgentOS プラグインに必要な host/timer と pane/status を、3 はアプリ内ブラウザ(browser.control)を、4 はパネル要素 card、grid、tabs、table、keyValue、stat、progress、callout、select、checkbox、code を加えます(パネルのデザイン)。6 は新しいターミナルをプラグインのプロキシ経由にする terminal/setProxy(terminal.proxy)を加えます。古いバージョンしか話せない Agentty は、実行できないものを入れる代わりにその旨を伝えます
activationEvents[]["onStartup"] なら Agentty と同時に起動、なければ最初の使用時。"onUninstall" ならアンインストール前に片付けを求める(plugin/uninstall)

Agentty はプラグインフォルダを作業ディレクトリとしてプログラムを起動します。wasm プラグインはプログラムを起動しません。モジュールは Agentty の中で動き、作業ディレクトリも環境変数もファイルもありません。

他のアプリとの連携#

フィールド説明
requires{ "name", "url", "note" } — このプラグインが対象とするアプリやサービス。カードが検出の有無を示し、なければリンクを出します
detect連携先アプリのパス(~ 可)。見つかればカードにおすすめが付きます

権限#

json
"permissions": ["net.request", "prompt.inject", "terminal.write", "session.read", "workspace.read", "mcp.tools"]
権限できること
net.requestプラグインが指定したアドレスへの HTTP リクエスト
prompt.injectプロンプトの送信
terminal.write開いているペインへの入力
session.readAI 会話の読み取り
workspace.readワークスペース一覧の取得、コンテキストのフォルダ・タイトル項目の参照
mcp.toolsAI エージェントにツールを提供。apiVersion: 5 と contributes.tools が必須
terminal.proxy新しいターミナルと AI セッションを、プラグインが動かすプロキシ経由にする。apiVersion: 6 が必須、wasm は不可

使うものだけを求めてください。一覧はインストール前に利用者へ表示され、権限のない呼び出しは失敗します。プラグインの権限を参照してください。

プラグインが加えるもの#

パネル#

json
"contributes": { "panel": { "title": "Hello", "icon": "sparkles", "surface": "sidebar", "mode": "push" } }

プラグインにボタンと、UI ツリーで満たすパネル(幅 360 px、縦スクロール)を与えます。SDK を参照してください。

surface はボタンの位置を決めます。

surface位置
pane(既定)ターミナル上のタブ列
sidebar左端のアクティビティバー、Agentty 自身のページと並んで
status下部のステータスバー

mode はパネルの開き方を決めます。利用者はパネルのレイアウトボタンで変更でき、その選択は保たれます。最初の動作は次のとおりです。

mode
push(既定)ターミナルの横にドッキングし、ターミナルが場所を空けます
overlay窓の右端に浮かび、他は動きません
window独立した窓。移動とサイズ変更ができます
fullターミナルとページが使う領域の全体

ドッキングしたパネルが残りの窓を押しつぶすほど大きくなることはありません。ドッキングできる幅を越えて引くと、浮かぶパネルになります。

コマンド#

json
"contributes": {
  "commands": [
    {
      "id": "hello.explain",
      "title": "Hello: Explain this folder",
      "description": "Sends a tour request to the focused agent",
      "icon": "bot",
      "palette": true
    }
  ]
}
フィールド説明
idプラグイン内で一意。SDK はこの id でハンドラを登録します
titleパレットに表示。プラグイン名を先頭に付けるとまとまって見えます
description任意の 2 行目
iconパレットでコマンドの横に表示されるアイコン名
palettefalse でコマンドパレットから隠す

コマンドはコマンドパレットから実行します。paneBar と when はなくなりました。これらが残っているマニフェストもこれまで通りインストール・実行でき、フィールドは無視されます。ただしそのボタンを前提に作られたプラグインはボタンを失い、コマンドはパレットから実行することになります。

AI エージェント向けツール#

json
"contributes": {
  "tools": [
    {
      "name": "list_containers",
      "description": "Lists the Docker containers this plugin manages, with their state.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "all": { "type": "boolean" }
        }
      },
      "readOnly": true
    }
  ]
}

プラグインは Agentty で動いている AI エージェント (Claude Code、Codex) へツールを提供できます。mcp.tools 権限と apiVersion: 5 が必須で、一緒に宣言する必要があります。

プラグインは、自分で動かすプロキシを経由させて新しいターミナルを通せます。terminal.proxy 権限と apiVersion: 6 が必須で、wasm プラグインでは使えません。

フィールド必須説明
nameはい1~48 文字。a-z、0-9、_ のみ、文字で始まる
descriptionはい1~1000 文字。エージェントが知るツールのすべて
inputSchemaJSON Schema、型は object、最大 16 KB
readOnlyブール値(既定値 false)。エージェントへのヒント

プラグインあたり最大 32 個のツール。プラグインは tools/call リクエストに文字列、任意の JSON 値、または MCP 形式のコンテンツ ({ "content": [...], "isError": false }) で応答します。詳細はプラグインプロトコルを参照してください。

アイコン#

icon には次の名前を使います。それ以外はパズルのピースとして表示されます。

text
app-window arrow-down arrow-left arrow-right arrow-up arrow-up-right at-sign bell bell-dot
blocks book-open bookmark bot brain bug calendar chart-column check chevron-down chevron-right
chevron-up circle-check circle-dot circle-user circle-pause circle-x clipboard clipboard-paste clock cloud
code columns-2 command container copy database download ellipsis external-link eye file-input
file-plus file-text folder folder-git-2 folder-open folder-plus git-branch git-commit-horizontal
git-pull-request globe grip-vertical hammer hash history house image info key-round
layout-panel-left lightbulb link list list-tree loader-circle mail maximize-2 message-circle-question
message-square message-square-code minimize-2 minus network notebook notebook-pen orbit package panel-left-close
panel-left-open pencil picture-in-picture-2 play plug plus power puzzle refresh-cw rocket rotate-cw
rows-2 save scroll-text search send settings shield-alert sparkles square square-plus
square-terminal star sticky-note tag terminal trash-2 undo-2 unlink upload users wand-sparkles
workflow wrench x zap git-fork file lock graduation-cap x-twitter

ロゴ#

ロゴはプラグイン自身の画像です。ストアの一覧、詳細カード、パネルのボタンで、icon の名前の代わりにこの画像が描画されます。

**ロゴはどこからも取得しません。**プラグインと一緒に運ばれるので、画面に描かれる絵はユーザーがインストールしたその絵です。そしてロゴを付けても、誰がインストールしたかが作者に伝わることはありません。

プラグインの種類ロゴのある場所
フォルダ — node、python、executable、または開発用にリンクしたフォルダ"logo": "logo.png"、プラグインフォルダ内のファイル
単一の wasm モジュール — ストアから来るすべてモジュールが画像を自分で持ちます。logo は使いません。Rust と WebAssemblyを参照

マニフェストのフィールドとしての logo はファイル名でしかありません。プラグインフォルダの外に出るパス(../)、絶対パス、スキームが付いた値(https:// のアドレスを含む)、400 文字を超える値はいずれも拒否され、プラグインは icon をそのまま使います。

モジュールが持つ画像は PNG・JPEG・GIF・WebP のいずれかで、名前ではなくバイトで実際の形式を確認し、512KB 以下である必要があります。それ以外はロゴではなく、プラグインは icon をそのまま使います。

**モジュールのロゴが SVG であることはありません。**どう名乗っていても同じです。SVG は絵ではなく文書だからです — レンダラーがその中に書かれたアドレスを解決するため、ローカルのパスが書かれていればそのファイルが開かれて描画されます。プラグインがロゴと称してユーザー自身のファイルを画面に出せてはなりません。

環境変数#

プログラムとして動くプラグイン(node, python, executable)には次の環境変数が渡されます。wasm プラグインには何も渡されず、必要なものは自身のストレージに置きます。

変数意味
AGENTTY_PLUGIN_IDプラグインの id
AGENTTY_PLUGIN_DIRプラグインフォルダ
AGENTTY_PLUGIN_DATA設定とキャッシュのための専用フォルダ
AGENTTY_VERSIONAgentty のバージョン
AGENTTY_LANGUAGE利用者の言語(en、ko、ja、zh、de)
AGENTTY_BINagentty コマンドラインツールのパス

保存するものはすべて AGENTTY_PLUGIN_DATA の中か、どちらの種類でも動く storage/* に置いてください。