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스토어 카드의 한 줄 설명
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를, 5는 AI 에이전트용 도구인 tools/call(mcp.tools)을, 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 트리로 채우는 패널(너비 360px, 세로 스크롤)을 줍니다. 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선택적 두 번째 줄
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, type은 object, 최대 16KB
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/*를 쓰세요.