Agentty/문서

Node.js SDK

핸들러, 호출, 패널 UI 빌더, 컨텍스트 객체 — agentty-plugin.mjs의 전체 기능.

agentty-plugin.mjs는 의존성이 없는 파일 하나입니다. 타입 정의는 같은 위치의 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 })한 줄 입력, 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단계, 문자열당 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": "ko"
}

플러그인이 보는 범위는 선언한 권한에 따라 달라집니다. 폴더와 이름 필드(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은 방해하면 안 됩니다.

다음으로#