Agentty/ドキュメント

Node.js SDK

ハンドラ、呼び出し、パネル UI ビルダー、コンテキストオブジェクト — agentty-plugin.mjs のすべて。

agentty-plugin.mjs は依存関係のない 1 ファイルです。型定義は同じ場所の agentty-plugin.d.ts にあります。プラグインページで開発者ガイドを押すと、両方が ~/.agentty/plugins/.sdk/ に展開されます。

Note

この方法で書いたプラグインは利用者のマシンでプログラムとして動き、PATH に Node.js 18 以降が必要で、フォルダか Git リポジトリからインストールされます。マーケットプレイスは WebAssembly モジュールしか受け付けません。そちらは Rust と WebAssembly を参照してください。

js
import { createPlugin, ui } from './agentty-plugin.mjs';

const plugin = createPlugin();
// ハンドラを登録…
plugin.start();

ハンドラはすべて start() の前に登録してください。

ハンドラ#

すべて async にできます。エラーはログに残り、利用者には通知として表示されます。

ハンドラ呼ばれるとき
onActivate(info => …)プラグインが起動した。info に plugin.dataDir、language、context
command(id, ({ context, args }) => …)コマンドパレットからコマンドが実行された
tool(name, handler)AI エージェントがツールを呼び出した。ハンドラが { args, context } を受け取り応答を返す。エラーはツールエラーとして送信される
onPanelOpen(context => …)パネルが表示された — ここで描画します
onPanelClose(context => …)パネルが隠れた
onEvent(elementId, (event, context) => …)その id の UI 要素が使われた
onAnyEvent((event, context) => …)onEvent が扱わなかったすべての UI イベント
onContextChange(context => …)フォーカス中のペイン、その状態、フォルダが変わった
onUrl(path, ({ path, query, url }) => …)agentty://plugin/<id>/<path>?… が開かれた
onShutdown(() => …)Agentty がプラグインを停止させる

呼び出し#

すべてプロミスを返します。

呼び出し権限
setPanel(tree) — パネルの内容を差し替える
showPanel() — このプラグインのパネルを開く
notify(message, kind) — info、success、warning、error
setBadge(text) — タブ領域のボタンに最大 8 文字
getContext()
hostInfo() — Agentty のバージョン、API バージョン、言語、描けるパネル要素(uiFeatures)
openUrl(url) — http/https
copy(text) — クリップボードにコピー
revealPath(path) — ファイルマネージャーで表示workspace.read
injectPrompt(request)prompt.inject
sendToTerminal({ paneId, text, submit })terminal.write
setTerminalProxy({ port, token }) · setTerminalProxy({ port: null })terminal.proxy
getSession({ paneId, maxTurns })session.read
listWorkspaces()workspace.read
fetch(request) — HTTP リクエストnet.request
log(...) — プラグインログ(stderr)に記録

プロトコルには storage/get・storage/set・storage/keys(プラグイン自身のフォルダにある JSON ドキュメント、権限不要。設定の同期をオンにすると、ユーザーの他のコンピュータにも同期されます)もあり、API バージョン 2 からは host/timer・pane/status もあります。Node のプラグインは自分でファイルを書いてもかまいませんが、storage はどちらの種類でも同じように動きます。プロトコルを参照してください。

plugin.info には initialize のデータが、plugin.context には最新のコンテキストが入っています。

パネル#

パネルは幅 360px で縦にスクロールします。プラグインがツリーで記述すると Agentty がネイティブに描くため、アプリと見た目が揃いウェブビューも要りません。何かが変わるたびに新しいツリーを送ってください。テキストフィールドは別の value を送らない限り、利用者が入力した内容を保ちます。

ビルダー要素イベント
ui.column(children, { gap }) / ui.row(children, { gap, wrap })レイアウト。gap: none、small、medium、large
ui.section(title, children)見出し付きのまとまり
ui.text(text, style)body、title、muted、small、code、error、success
ui.button(id, label, { icon, variant, disabled })primary、secondary、ghost、dangerclick
ui.input(id, { placeholder, value, rows })1 行入力、rows が 1 より大きければその行数のテキストエリア(最大 24)入力が止まると change、Enter で submit。event.value が文字列
ui.list(id, items, { empty })行 { id, title, subtitle, detail, icon, tone, actions }event.item を伴う select、行のボタンは event.item・event.action を伴う action
ui.choice(id, [{ value, label }], value)分割選択値を伴う change
ui.toggle(id, label, value)スイッチ新しい真偽値を伴う change
ui.badge(text, tone)neutral、info、success、warning、error
ui.spinner(text)
ui.divider()
ui.flow(id, steps)手順 { id, title, subtitle, icon, state, selected, side }、state: off、on、active、done、errorevent.item を伴う select
ui.popover(id, title, children)パネルの横のカードclose
ui.card(children, { title, subtitle, icon, tone })浮いた箱。tone はアイコンと縁の色(API 4)
ui.grid(children, { columns, gap })等幅の列 1–6(API 4)
ui.tabs(id, [{ id, label, icon, badge }], value, children)タブ。children は選ばれたタブの中身(API 4)タブの id を伴う change
ui.table(id, [{ label, align, grow }], [{ id, cells, tone }], { empty, selected })見出しの下の行(API 4)event.item を伴う select
ui.keyValue([{ label, value, tone, mono }])ラベルと値の組(API 4)
ui.stat(label, value, { detail, icon, tone })大きく見せる数字ひとつ(API 4)
ui.progress(value, { label, detail, tone })バー、value は 0 から 1(API 4)
ui.callout(text, { title, icon, tone })色付きの注記、既定は info(API 4)
ui.select(id, [{ value, label }], value, { placeholder, disabled })ドロップダウン(API 4)値を伴う change
ui.checkbox(id, label, value, { description, disabled })チェックボックス(API 4)新しい真偽値を伴う change
ui.code(text, { language, title })色分けされたコードとコピーボタン(API 4)

null と false の子要素は飛ばされるので、条件 && ui.text('…') がそのまま動きます。

何にどの要素を使うか、そのまま出発点にできる画面一式は パネルのデザイン にあります。API 4 と記した要素を使うにはマニフェストに "apiVersion": 4 が必要です。

js
plugin.onPanelOpen(async (context) => {
  const notes = await search('');
  plugin.setPanel(
    ui.column([
      ui.input('q', { placeholder: 'Search notes' }),
      ui.list('notes', notes.map((n) => ({
        id: n.path,
        title: n.title,
        subtitle: n.folder,
        icon: 'notebook',
        actions: [{ id: 'insert', icon: 'send', tooltip: 'Insert into the focused pane' }],
      })), { empty: 'No notes yet' }),
    ]),
  );
});

plugin.onEvent('notes', (event, context) => {
  if (event.event === 'action' && event.action === 'insert') {
    return plugin.injectPrompt({ text: read(event.item), target: 'ask' });
  }
});
Note

制限: 要素 2,000 個、深さ 12 階層、文字列 1 つあたり 20,000 文字。choice の選択肢とリスト項目のボタンも要素として数えます。パネルの再描画は最短 50ms 間隔、通知は最短 700ms 間隔です。毎秒 240 件を超えて送るプラグインは暴走とみなされ停止します。

コンテキスト#

すべてのコマンド・イベント・パネル呼び出しには、フォーカス中のウィンドウのコンテキストが付きます。

json
{
  "workspace": { "id": 3, "name": "agentty", "cwd": "/Users/me/agentty", "active": true },
  "pane": {
    "id": 12,
    "kind": "claude",
    "tool": "claude",
    "title": "Claude Code",
    "cwd": "/Users/me/agentty",
    "sessionId": "…",
    "status": "idle",
    "running": true
  },
  "language": "ja"
}

見える範囲は宣言した権限で決まります。フォルダと名前の項目(workspace.cwd、workspace.name、pane.cwd、pane.title)には workspace.read が、pane.sessionId には session.read が必要です。権限がなければ id、kind、tool、status、running、言語だけが残ります。どのペインがフォーカスされているかは分かっても、利用者がどこで作業しているかは分かりません。

kind は claude、codex、shell です。他のエージェント CLI は shell ペインで動き、tool が名前を示します。

status意味
idle入力待ち
workingツールを実行中
thinkingターンが開いており、ツール呼び出しの合間
finishedターンが終わった
permission許可を求めている
question利用者に質問している
interrupted利用者が中断した
shell通常のシェル
exitedプログラムが終了した

邪魔しないかどうかを判断するときは working と thinking を同じに扱ってください。

プロンプトを送る#

js
await plugin.injectPrompt({
  text: 'Continue the release checklist.',
  title: 'Release',          // 新規セッションのワークスペース名、ダイアログの見出し
  target: 'ask',             // ask | active | newWorkspace | newTab | pane | workspace
  agent: 'claude',           // 新規セッション用の claude | codex | shell
  cwd: '/Users/me/project',  // 新規セッションのフォルダ
  submit: true,              // Enter を押す(エージェントのみ)
});
  • ask(既定)は**送信先…**を出し、利用者に行き先を選ばせます。
  • active はフォーカス中のペイン、pane は paneId、workspace は workspaceId に入力し、newWorkspace・newTab はそのプロンプトで新しいセッションを始めます。
  • ターミナルには常に入力されるだけです。injectPrompt が Enter を押すことはありません。
  • 60,000 バイトを超えるプロンプトは ~/.agentty/prompts/ に保存され、そのファイルを読むようエージェントに伝えられます。Windows では、エージェントのコマンドラインに収まらない長さ(約 30,000 文字)のプロンプトも同様です。

他のアプリやリンクから始まるものには ask を使ってください。

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

js
plugin.tool('list_containers', async ({ args }) => {
  const containers = await listContainers({ all: args.all === true });
  return containers.map((c) => `${c.name}: ${c.state}`).join('\n');
});

plugin.start() 呼び出しの前にツールを登録してください。エージェントがツールを呼び出すと、あなたの応答(文字列、任意の JSON 値、MCP 形式のコンテンツ)が受け取られます。ハンドラで投げたエラーはツールエラーとしてエージェントに送信されます。

プラグインはツールを提供するために mcp.tools 権限と apiVersion: 5 を宣言する必要があります。プラグインあたり最大 32 個のツール。スキーマと制限はマニフェストリファレンスを参照してください。

セッションとターミナル#

新しいターミナルをプロキシ経由にするには、terminal.proxy 権限と apiVersion: 6 を宣言し、plugin.setTerminalProxy({ port, token }) を呼びます。plugin.setTerminalProxy({ port: null }) でプロキシを止めます。アドレスは Agentty がポートから 127.0.0.1 に組み立てるため、プラグインはターミナルを別の場所へ向けられません。詳しくは権限を参照してください。

js
const session = await plugin.getSession({ paneId: context.pane.id, maxTurns: 200 });
// { agent, sessionId, title, cwd, status, turnCount, turns: [{ role: 'user' | 'assistant', text }] }

await plugin.sendToTerminal({
  paneId: context.pane.id,
  text: 'Summarize what we did.',
  submit: true,
});

エージェントに入力する前に pane.status を確認してください。working、permission、question は邪魔してはいけません。

次に読むもの#