플러그인 프로토콜
SDK 뒤에서 오가는 JSON-RPC 와이어 포맷, WebAssembly 모듈 ABI, 그리고 모든 메시지와 제한, 오류 코드.
SDK 없이 플러그인을 작성할 때 쓰는 와이어 포맷입니다. Node.js SDK와 Rust SDK가 이 내용을 모두 감싸 줍니다. 어느 쪽이든 빠른 시작을 먼저 읽으세요.
API 버전 1은 이 페이지에서 아래 것들을 뺀 전부입니다. host/timer와 pane/status는 버전 2, UI 트리에서 API 4로 표시된 패널 요소는 버전 4, tools/call은 버전 5, terminal/setProxy는 버전 6입니다.
전송 방식#
Agentty는 플러그인 폴더를 작업 디렉터리로 삼아 프로그램을 시작합니다.
runtime | 실행 명령 |
|---|---|
node | node <main> — 로그인 셸 PATH, Homebrew, Volta, nvm의 Node.js |
python | python3 <main> |
executable | <main> |
wasm | 없음 — <main>이 Agentty가 직접 실행하는 WebAssembly 모듈. WebAssembly 플러그인 참고 |
메시지는 JSON-RPC 2.0 객체이며 한 줄에 하나, UTF-8로, stdin(Agentty → 플러그인)과 stdout(플러그인 → Agentty)으로 오갑니다. 16MB가 넘는 줄은 거부됩니다. stdout에 나온 JSON이 아닌 내용은 로그에 남기고 무시합니다. stderr는 플러그인 로그로 갑니다.
stdin이 닫히거나 shutdown이 오면 종료하세요. shutdown 후 1.5초가 지나도 살아 있으면 SIGTERM을, 다시 1.5초 뒤에 SIGKILL을 받습니다. Agentty가 종료될 때는 둘 다 즉시 이어집니다.
Agentty → 플러그인#
| 메시지 | 종류 | params |
|---|---|---|
initialize | 요청 — 응답 필요 | { apiVersion, agentty: { version }, plugin: { id, name, version, dir, dataDir }, language, context } |
command/execute | 알림 | { command, args, context } |
panel/open · panel/close | 알림 | { context } |
ui/event | 알림 | { element, event, value?, item?, action?, context } |
context/changed | 알림 | { context } |
url/open | 알림 | { path, query, url, context } |
pane/status | 알림 | { paneId, status, running, agent, title, cwd } — 이 플러그인이 시작한 페인의 상태가 바뀜 (workspace.read, API 2) |
tools/call | 요청 — 응답 필요 | { name, arguments, context } — AI 에이전트가 도구를 호출함 (mcp.tools, API 5) |
plugin/uninstall | 요청 — 응답 필요 | { context } — 사용자가 플러그인을 제거하는 중입니다. 매니페스트의 activationEvents에 onUninstall이 있을 때만 보내며, 실행 중이 아니면 먼저 시작합니다. 데이터 폴더 밖에 만든 것(설치한 보조 프로그램 등)을 지운 뒤 응답하세요. Agentty는 최대 5초 기다린 뒤 어느 쪽이든 제거합니다 |
shutdown | 알림 | {} |
initialize가 먼저 오고, 바로 뒤에 플러그인을 시작하게 한 메시지(명령, 패널 열기, 링크)가 옵니다. initialize에는 아무 결과나 응답하면 됩니다(예: {}).
플러그인 → Agentty#
결과나 오류를 받으려면 요청(id 포함)으로, 필요 없으면 알림(id 없음)으로 보냅니다.
| 메서드 | 권한 | params | 결과 |
|---|---|---|---|
ui/setPanel | { tree } | null | |
ui/showPanel | {} | null | |
ui/notify | { message, kind } — info, success, warning, error | null | |
ui/setBadge | { text }, 최대 8자 | null | |
context/get | {} | 컨텍스트 | |
host/info | {} | { version, apiVersion, language, uiFeatures } | |
host/openUrl | { url } — http/https | null | |
host/copy | { text } — 최대 100,000자 | null | |
host/timer | { ms } — API 2 | 시간이 지나면 { elapsedMs } | |
host/revealPath | workspace.read | { path } — 존재하는 절대 경로 | null |
prompt/inject | prompt.inject | { text, title?, target?, paneId?, workspaceId?, agent?, cwd?, submit? } | { status: "asked" } 또는 { status: "sent", paneId } |
terminal/send | terminal.write | { paneId?, text, submit? } — paneId 없으면 포커스된 페인 | { paneId } |
terminal/setProxy | terminal.proxy | { port, token } (token: 16~128자의 문자, 숫자, -, _) 또는 { port: null } — 이후 여는 터미널은 플러그인의 127.0.0.1 프록시를 거침 | null |
session/get | session.read | { paneId?, maxTurns? } — 기본 200, 최대 2000 | { paneId, agent, sessionId, title, cwd, status, turnCount, turns } |
workspace/list | workspace.read | {} | [{ id, name, cwd, active, panes }] |
net/fetch | net.request | { url, method?, headers?, body?, timeoutMs?, proxy? } | { status, statusText, url, headers, body, truncated, binary, bytes, durationMs } |
storage/get | { key } | { key, value } — 값이 없으면 value는 null | |
storage/set | { key, value } — null이면 삭제 | null | |
storage/keys | {} | [key] |
700ms보다 빠르게 도착하는 ui/notify는 정상 응답 후 폐기되며, 초당 240건을 넘게 보내는 플러그인은 중단됩니다. 컨텍스트 필드는 플러그인의 권한에 따라 제한됩니다.
네트워크에 닿기#
net/fetch는 플러그인이 네트워크에 닿는 유일한 방법입니다. Agentty가 거는 제한(메서드, 헤더, 크기, 타임아웃, 리다이렉트)은 권한에 정리해 두었습니다. 요약하면 요청에는 여러분의 것이 아무것도 실리지 않습니다. 쿠키도 저장된 자격 증명도 없고, 플러그인이 직접 넣은 것만 갑니다.
에이전트의 도구 호출에 응답하기 (API 4)#
AI 에이전트가 도구를 호출하면 Agentty가 tools/call을 { name, arguments, context }로 보냅니다. 문자열, 어떤 JSON 값, 또는 MCP 형식 컨텐츠 { "content": [{ "type": "text", "text": "…" } | { "type": "image", "data": "<base64>", "mimeType": "image/png" }], "isError": false }로 응답하세요. 다른 컨텐츠 타입은 폐기됩니다. JSON-RPC 오류로 응답해도 됩니다. 그 메시지는 오류로 에이전트에 전달됩니다.
플러그인은 120초 이내에 응답해야 합니다. 한 플러그인에서는 최대 8개 호출이 기다릴 수 있습니다. 인수는 최대 256KB입니다. 에이전트에 전달되는 텍스트는 100,000자에서 잘립니다.
기다리기, 그리고 에이전트가 끝난 것을 듣기#
host/timer로 플러그인은 기다릴 수 있습니다. 시간이 지나면 응답이 오는 요청이고 최소 100ms, 최대 1시간, 동시에 8개까지입니다. 모듈은 메시지를 처리하는 동안에만 실행되므로 나중에 다시 일을 이어 가려면 이것밖에 없습니다. 플러그인이 받는 것은 그 응답뿐이어서 백그라운드 실행 수단은 되지 못합니다.
pane/status로 플러그인은 자기가 시작한 에이전트가 끝났는지 알 수 있습니다. 플러그인은 prompt/inject의 응답({ status: "sent", paneId })에서 페인 id를 얻습니다. Agentty는 어느 플러그인이 어느 페인을 시작했는지 기억했다가 그 플러그인에게만 상태 변화를 알립니다. working, idle, finished, permission, question, interrupted, exited, 그리고 마지막에 한 번 closed입니다. 동시에 최대 32개 페인까지 추적합니다.
이용자가 직접 보낸 프롬프트도 추적됩니다. target: "ask"는 아직 페인이 없어서 페인 id 없이 { status: "asked" }로 응답합니다. 그래도 이용자가 고른 세션을 똑같이 지켜봅니다. 플러그인은 그 세션의 첫 pane/status를 받고서야 어느 페인인지 알게 됩니다. 질문이 여럿 열려 있는 플러그인은 프롬프트에 붙인 title로 구분합니다.
화면이 그려지고 있든 아니든 상태는 전달됩니다. 다른 창에 가려진 창이나 잠긴 화면의 창은 그려지지 않습니다. 에이전트를 기다리는 플러그인이 이용자가 돌아올 때까지 기다려서는 안 됩니다. AgentOS 플러그인이 이 둘을 바탕으로 만들어졌습니다.
기억하기#
storage/*는 플러그인이 실행 사이에 기억하는 수단입니다. 자기 폴더의 JSON 문서 하나(<데이터 폴더>/plugin-data/<plugin>/storage.json, 0600으로 생성)를 키로 읽고 씁니다. 키는 소문자·숫자·.·-·_로 쓰며 최대 64개, 총 1MB입니다. 프로세스로 실행되는 플러그인은 자기 파일을 쓸 수 있습니다. WebAssembly 플러그인은 파일이 없으니 무언가를 남기려면 이것을 써야 합니다.
오류 코드#
| 코드 | 의미 |
|---|---|
-32601 | 알 수 없는 메서드 |
-32602 | 잘못된 파라미터 — 잘못된 UI 트리, 존재하지 않는 페인 등 |
-32001 | 권한 없음, 또는 링크가 도달해 차단된 상태 — 재시작할 때까지 |
-32002 | 사용 불가 — 열린 창이 없음, 세션이 아직 없음 |
주고받는 예시#
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"apiVersion":1,"plugin":{"id":"hello"},"language":"en","context":{}}}
→ {"jsonrpc":"2.0","method":"panel/open","params":{"context":{}}}
← {"jsonrpc":"2.0","id":1,"result":{}}
← {"jsonrpc":"2.0","id":1,"method":"ui/setPanel","params":{"tree":{"type":"column","children":[{"type":"button","id":"go","label":"Go"}]}}}
→ {"jsonrpc":"2.0","id":1,"result":null}
→ {"jsonrpc":"2.0","method":"ui/event","params":{"element":"go","event":"click","context":{}}}
← {"jsonrpc":"2.0","id":2,"method":"prompt/inject","params":{"text":"Hello","target":"ask"}}
→ {"jsonrpc":"2.0","id":2,"result":{"status":"asked"}}→는 Agentty에서 플러그인으로, ←는 플러그인에서 Agentty로입니다. 요청 id는 방향별로 셉니다.
WebAssembly 플러그인#
"runtime": "wasm"으로 지정하면 main은 Agentty가 자기 안에서 인터프리터로 실행하는 .wasm 모듈이 됩니다. 파일 하나가 macOS·Windows·Linux에서 그대로 동작합니다.
모듈은 Agentty가 건네준 함수만 호출할 수 있습니다. 파일도, 소켓도, 환경 변수도, 프로세스도 없고, 카운터 말고는 시계도 없습니다. WebAssembly 플러그인은 어떻게 작성했든 ~/.agentty도, 이용자의 프로젝트도, 자격 증명도 읽을 수 없습니다. Agentty에 무언가를 요청할 때는 프로세스 플러그인이 stdout에 쓰는 것과 똑같은 메시지를 보내며, 매니페스트의 권한도 똑같이 검사합니다.
모듈이 export하는 것:
| Export | 의미 |
|---|---|
memory | 선형 메모리 — Rust나 C 모듈의 표준 export |
agentty_alloc(len: i32) -> i32 | Agentty가 메시지를 써 넣을 len 바이트 버퍼 |
agentty_on_message(ptr: i32, len: i32) | Agentty가 보낸 UTF-8 JSON 메시지 하나 |
그리고 agentty라는 모듈에서 import하는 것:
| Import | 의미 |
|---|---|
send(ptr: i32, len: i32) | Agentty로 보내는 UTF-8 JSON 메시지 하나 |
log(ptr: i32, len: i32) | 플러그인 로그에 남길 한 줄 |
now_ms() -> i64 | Unix epoch 기준 밀리초 |
메시지는 stdio로 오가는 것과 같은 JSON-RPC 객체이며, 호출마다 하나씩 줄바꿈 없이 전달됩니다. 이외의 것을 import하는 모듈은 로드되지 않습니다. 64MB가 넘는 모듈도 거부하고 메모리는 64MB로 제한하며 메시지마다 작업량 예산을 둡니다. 돌아오지 않는 플러그인은 "제시간에 끝내지 못함"으로 중단됩니다. 메시지 하나를 처리하는 동안 256개가 넘는 메시지를 보내는 플러그인도 중단됩니다. send와 log를 합쳐서 세므로 로그만 찍는 루프도 공짜가 아닙니다.
Rust SDK가 이 모든 것을 감춰 줍니다.
UI 트리#
모든 노드는 type을 가진 객체입니다.
column { children, gap? } gap: none | small | medium | large
row { children, gap?, wrap? }
section { title, children }
text { text, style? } style: body | title | muted | small | code | error | success
button { id, label, icon?, variant?, disabled? } variant: primary | secondary | ghost | danger
input { id, placeholder?, value?, rows?, mono? }
mono: 고정폭 글꼴 (API 4)
completions (API 4): [{ label, insert?, detail? }] 입력 중인 단어의 자동완성.
앞의 {{ 와 뒤의 }} 도 함께 바뀝니다
rows > 1: 그만큼의 줄을 가진 텍스트 영역(최대 24). Enter는 줄을
바꾸고, 붙여넣기는 줄바꿈을 유지합니다
list { id, items, empty? }
items: [{ id, title, subtitle?, detail?, icon?, tone?, actions?: [{ id, label?, icon?, tooltip? }] }]
depth: 트리 들여쓰기 0–8, tag: 제목 앞 짧은 라벨(8자 이하), 색은 tagTone (API 4)
choice { id, options: [{ value, label }], value? }
toggle { id, label, value? }
badge { text, tone? } tone: neutral | info | success | warning | error
spinner { text? }
divider {}
flow { id, steps: [{ id, title, subtitle?, icon?, state?, selected?, side? }] }
state: off | on | active | done | error — 자동화의 단계를 위에서 아래로
popover { id, title, children } 패널 옆의 카드. 트리의 첫 번째 것이 열립니다
API 4:
card { children, title?, subtitle?, icon?, tone? } 떠 있는 상자. tone은 아이콘과 테두리 색
grid { children, columns?, gap?, widths? } 같은 폭의 열(1–6, 기본 2), 넘치면 다음 줄로
widths: 열마다 "240px"(고정) 또는 "2"(비율) — columns 대신
id?, resizable? (API 4): 첫 고정 열을 끌어서 폭 조절, 끝나면 resize(폭)
fill: 남은 높이를 채우고 열마다 따로 스크롤 (API 4)
tabs { id, tabs: [{ id, label, icon?, badge?, closable? }], value, children }
closable: 닫기 버튼, 누르면 close
children: 선택된 탭의 내용만
table { id, columns: [{ label, align?, grow? }], rows: [{ id, cells, tone? }], empty?, selected? }
align: start | center | end, grow: 폭의 비율(1–12), 열마다 셀 하나
keyValue { items: [{ label, value, tone?, mono? }] }
stat { label, value, detail?, icon?, tone? }
progress { value, label?, detail?, tone? } value는 0부터 1까지, detail은 퍼센트 대신 표시
callout { text, title?, icon?, tone? } tone 기본값은 info
select { id, options: [{ value, label }], value?, placeholder?, disabled? }
checkbox { id, label, value?, description?, disabled? }
code { text, language?, title? } language(rust, json, ts, sh, …)로 색칠, 복사 버튼 포함
API 5:
image { src?, id?, alt?, width?, height?, fit?, caption?, placeholder?, drop?, into? }
플러그인 자기 폴더(files/*)의 그림: PNG·JPEG·WebP·GIF만, SVG는 그리지 않음;
높이 기본 240; fit: contain | cover; src가 없으면 빈 칸; drop(id와 함께,
files 권한 필요)은 Finder에서 끌어 놓은 그림을 받음
graph { id, nodes, edges?, height?, movable?, fill? }
캔버스의 x, y에 놓인 노드 카드를 와이어로 잇는 그래프(이미지 파이프라인처럼); fill이면 패널의
남은 높이를 차지; 그 안에서 스크롤·확대/축소(− % + 맞춤, ⌘/Ctrl + 스크롤)
nodes: [{ id, title, subtitle?, icon?, tone?, x, y, width?, inputs?, outputs?, children?, state?, selected? }]
edges: [{ from: { node, port }, to: { node, port }, tone?, idle? }]이벤트: button은 click, input은 value와 함께 change·submit, list는 item과 함께 select(행 버튼은 item·action과 함께 action), choice는 선택한 값과 함께 change, toggle은 새 불리언과 함께 change를 보냅니다.
리스트 항목의 tone은 아이콘 색을 정하며 badge와 같은 값을 씁니다.
flow는 단계 id를 item으로 담아 select를, popover는 닫기 버튼에서 close를 보냅니다. API 4부터: tabs는 탭 id와 함께 change, table은 행 id를 item으로 담아 select, select는 옵션 값과 함께 change, checkbox는 새 불리언과 함께 change를 보냅니다. API 5부터: image는 click을, 그리고 [{ path, name, size }]와 함께 drop을 보냅니다(files/pick처럼 플러그인 폴더에 복사된 경로). graph는 노드 헤더를 누르면 노드 id를 item으로 담아 select를, movable이면 헤더를 끌어 놓았을 때 노드를 item, { x, y }를 value로 담아 move를 보냅니다. 플러그인은 그 위치를 기억해 다시 보내 주세요.
API 4 요소를 쓰는 플러그인은 매니페스트에 "apiVersion": 4를 적습니다. 실행 중인 Agentty가 그릴 수 있는 요소는 host/info의 uiFeatures에 있습니다. 무엇에 어떤 요소를 쓸지는 패널 디자인을 보세요.
Agentty 없이 테스트하기#
node·python·executable 플러그인은 stdin을 읽고 stdout에 쓰는 평범한 프로그램이므로 테스트에서 직접 구동할 수 있습니다. initialize 요청을 쓰고 확인할 알림을 이어서 보낸 뒤 플러그인이 돌려주는 JSON을 검증하면 됩니다.
wasm 모듈도 방식은 같습니다. 위의 import 세 개를 제공할 수 있는 WebAssembly 런타임이면 무엇으로든 구동할 수 있습니다.