Agentty/문서

플러그인

플러그인이 Agentty에 무엇을 더하는지, 마켓플레이스나 내 폴더에서 설치하는 법, 그리고 믿고 쓰기 전에 확인할 것.

플러그인은 Agentty를 다른 앱과 연결하고 터미널에 도구를 더합니다. 터미널 옆에 패널을 두고, 에이전트 페인 위에 버튼을 추가하고, 명령 팔레트에 항목을 넣고, 텍스트를 프롬프트로 에이전트에 넘길 수 있습니다. 프롬프트를 어디로 보낼지는 플러그인이 이용자에게 묻지 않는 한 플러그인이 정합니다. 그러니 카드에 적힌 권한을 한번 읽어 보세요.

플러그인은 Agentty가 나아가는 방향이기도 합니다. FDE(전방 배치 엔지니어)가 자기가 일하는 현장에 맞춰 만들듯 플러그인은 에이전트를 한 환경(팀·고객·상황)에 맞춥니다. Agentty는 그 에이전트를 모두 한곳에서 같은 방식으로 실행합니다. 소개를 참고하세요.

직접 만들고 싶다면 플러그인 빠른 시작부터 보세요.

에이전트는 다양하게, 환경은 하나로: FDE 방향#

FDE(Forward Deployed Engineer, 전방 배치 엔지니어)는 일이 있는 현장 — 고객의 시스템과 계정, 일하는 방식 — 으로 들어가 그곳에 맞는 에이전트를 만듭니다. Agentty도 이 방향으로 커 가고 있습니다. 플러그인으로 환경별·상황별로 맞는 에이전트를 만들고, 그 에이전트들이 실행되는 환경은 Agentty 하나로 통합합니다. 에이전트를 몇 가지나 만들든 만들고 실행하는 곳은 모두 같은 환경입니다.

플러그인으로 에이전트를 맞춤현장마다, 팀마다, 상황마다 그에 맞는 에이전트를 둡니다. 할 일과 패널, 일해도 되는 사이트, 단계마다 맡길 에이전트와 모델까지 플러그인에 담깁니다(AgentOS 플러그인).
실행은 Agentty 하나에서어떤 에이전트든 같은 터미널에서 같은 상태 표시, 같은 권한, 같은 보낼 곳… 승인으로 돌아갑니다. 고객마다 실행 환경을 새로 꾸리지 않습니다.
다음 현장으로 그대로한 환경에서 통한 에이전트는 플러그인째로 다음 환경에 가져갑니다. 폴더나 Git에서 설치하고, 처음부터 다시 만드는 대신 그 자리에 맞게 고쳐 씁니다.

플러그인 페이지#

액티비티 바의 퍼즐 아이콘, 보기 → 플러그인, 또는 명령 팔레트(⇧⌘P → "플러그인")로 엽니다.

  • 설치됨 — 보유한 모든 플러그인과, 무엇을 더하고 무엇을 할 수 있는지.
  • 마켓플레이스 — Agentty가 제공하는 플러그인 목록. 자체 플러그인도 포함됩니다. 아래를 참고하세요.
  • 사용 가능 — Agentty에 기본 포함된 플러그인. 연동 대상 앱이 설치돼 있으면 추천으로 표시됩니다.
  • 직접 만들기 — AI로 플러그인을 만들거나, Git 저장소나 폴더에서 설치합니다.

설치된 플러그인마다 활성화/비활성화, 패널 열기, 재시작(코드 수정 후), 업데이트(내장 플러그인의 새 버전이 나왔을 때), 로그(플러그인이 출력한 내용과 크래시), Finder에서 보기, 삭제(두 번 눌러 확인)가 있습니다.

플러그인은 Agentty를 켤 때가 아니라 처음 쓸 때 시작합니다. 그래서 쓰지 않는 플러그인은 아무 부담이 없습니다.

설치#

출처방법
마켓플레이스마켓플레이스 카드의 설치
내장사용 가능 카드의 설치
Git 저장소직접 만들기 아래에 https:// 주소를 붙여넣고 Git에서 설치
폴더폴더에서 설치… 가 ~/.agentty/plugins/로 복사합니다
편집 중인 폴더개발용 폴더 연결… 은 그 자리에서 실행하며, 삭제해도 연결만 해제됩니다

플러그인 폴더를 ~/.agentty/plugins/에 직접 복사한 뒤 새로 고침을 눌러도 됩니다.

무엇을 신뢰하게 되는가#

설치 전에 카드의 권한 아래에 그 플러그인이 할 수 있는 일이 완전한 문장으로 표시됩니다. HTTP 요청 보내기, 에이전트 세션 시작하기, 터미널에 입력하기, AI 대화 읽기, 워크스페이스 보기입니다.

정보 → 실행 방식에는 플러그인이 아래 두 가지 중 어느 쪽인지 나옵니다. 둘은 성격이 전혀 다릅니다.

WebAssemblyAgentty가 모듈을 직접 실행합니다. 자기 파일도, 프로세스도, 네트워크도 없습니다. 어떻게 작성했든 위 권한이 허용한 것에만 닿습니다.
프로그램 (node, python, 실행 파일)이용자 계정으로 실행되고, 이용자가 띄우는 다른 프로그램과 접근 범위가 같습니다. 권한은 Agentty를 거치는 동작만 막을 뿐, 프로그램 자체를 막는 장치는 없습니다.
Important

프로그램 플러그인은 제작자를 신뢰할 때만 설치하세요. 마켓플레이스에 있는 것은 모두 WebAssembly입니다. 그래서 목록에서 바이너리를 받아 설치해도 안전합니다.

전체 구조는 플러그인 권한에 있습니다.

마켓플레이스#

플러그인 → 마켓플레이스는 Agentty-Marketplace가 제공하는 목록을 보여줍니다. 플러그인은 풀 리퀘스트로 추가하며, 올라가는 것은 소스가 공개된 WebAssembly 모듈뿐입니다. Agentty 자체 플러그인도 같은 조건으로 올라가 있고, 애플리케이션에 내장된 것은 없습니다.

설치할 때는 이렇게 됩니다.

  1. Agentty가 HTTPS로 목록을 읽고 모든 항목을 여기서 다시 검사합니다. id, 문구, 권한, 모듈이 오는 호스트까지요. 검사를 통과하지 못한 항목은 아예 목록에 나오지 않습니다.
  2. 카드에 플러그인이 무엇인지, 소스가 어디 있는지, 라이선스, 모듈 크기와 체크섬, 할 수 있는 일이 나옵니다.
  3. 설치를 누르면 Agentty가 모듈을 내려받아 그 체크섬과 대조합니다. 일치하기 전에는 플러그인 폴더에 아무것도 들어가지 않습니다.

항목에는 모듈이 어느 플러그인 프로토콜로 만들어졌는지도 적혀 있습니다. 그보다 낮은 버전만 아는 Agentty는 플러그인을 목록에 보여 주지만, 설치를 제안하지 않고 최신 Agentty가 필요하다고 알립니다.

혼자 쓰는 플러그인은 이 목록을 거치지 않아도 됩니다. 폴더에서 설치… 와 Git에서 설치는 어떤 플러그인이든 받습니다.

사용하기#

  • 패널 — 패널이 있는 플러그인은 버튼이 생깁니다. 터미널 위 탭 영역, 왼쪽 가장자리의 액티비티 바, 또는 아래쪽 상태 바 중 플러그인이 고른 자리입니다. 클릭하면 패널이 열리고 다시 클릭하면 닫힙니다. 패널 헤더의 ↻는 플러그인을 재시작하고, 톱니바퀴는 플러그인 페이지를 엽니다.
  • 명령 팔레트 — ⇧⌘P의 플러그인 항목에 모든 플러그인 명령이 나열됩니다.

패널이 열리는 자리#

패널의 레이아웃 버튼으로 여는 방식을 바꿀 수 있고, 고른 방식은 기억됩니다.

도킹터미널 옆에 붙고, 터미널이 자리를 비켜 줍니다
떠 있기창 오른쪽 가장자리에 떠 있고, 다른 것은 움직이지 않습니다
독립 창별도의 창. 이동과 크기 조절이 가능합니다
전체터미널과 페이지가 쓰는 영역 전체

도킹된 패널은 창의 나머지 부분을 밀어낼 만큼 커지지 않습니다. 도킹 가능한 범위를 넘겨 끌면 떠 있는 패널이 됩니다.

"보낼 곳…" 다이얼로그#

플러그인이나 다른 앱의 링크가 프롬프트를 보내면, Agentty는 무엇을 보낼지 보여 주고 고르게 합니다.

  • Claude Code / Codex / 터미널
  • 새 워크스페이스(폴더 변경 가능), 현재 워크스페이스의 새 탭, 또는 열려 있는 워크스페이스 중 하나 — 그곳의 유휴 에이전트가 받고, 없으면 새 에이전트 탭이 열립니다
  • 바로 전송 — 체크를 풀면 텍스트만 입력하고 Enter는 누르지 않습니다

터미널에는 입력만 됩니다. 이 경로로 보낸 프롬프트에는 Enter가 눌리지 않습니다. 보내기를 누르기 전에는 아무것도 전송되지 않습니다.

terminal.write는 이와 다릅니다. 이 권한이 있는 플러그인은 열린 터미널에 입력하고 Enter까지 누릅니다. 셸이라면 그 명령이 그대로 실행됩니다. 그 앞을 막는 다이얼로그가 없어서 카드가 이 권한을 따로 짚어 보여 줍니다.

다른 앱에서 오는 링크#

다른 앱은 agentty:// 링크로 Agentty에 작업을 넘길 수 있습니다. Cosmica의 "Agentty에서 계속하기"가 그 예입니다.

링크동작
agentty://plugin/<id>/<path>?key=value플러그인 <id>를 시작하고 URL 핸들러를 호출
agentty://prompt?text=…&title=…&agent=…&cwd=…해당 텍스트로 **보낼 곳…**을 엽니다 (file=로 절대 경로의 .md·.txt 첨부)
agentty://plugins/<id>플러그인 페이지의 해당 플러그인을 엽니다

링크에 필요한 내장 플러그인이 아직 없으면 Agentty가 설치를 제안하고, 설치한 뒤 링크를 이어서 처리합니다. 이 경로로 들어온 프롬프트는 언제나 **보낼 곳…**을 거칩니다.

Note

링크는 설치된 애플리케이션에서 동작합니다. 개발용으로 실행한 빌드는 운영체제에 agentty:// 처리기로 등록되지 않습니다.

Cosmica#

Cosmica는 노트 앱입니다. 플러그인은 Agentty에 기본 포함되어 있고, Cosmica가 설치돼 있으면 추천으로 표시됩니다. Cosmica 설정에서는 노트 폴더와 로컬 포트만 읽습니다.

  1. 플러그인 → 설치를 Cosmica 카드에서 누르고, 탭 영역에서 패널을 엽니다.
  2. 이 세션 저장 (패널 맨 위) — Claude Code나 Codex 페인에 포커스를 두고 Cosmica에 저장을 누르세요. 에이전트가 목표·수행 내용·변경된 파일·결정·다음 단계를 정리한 요약을 아래에서 고른 폴더에 씁니다. 폴더 목록은 Cosmica 노트에서 가져옵니다. 기본값은 Agentty이고, 이 폴더는 처음 저장할 때 만들어집니다. + 새 폴더로 다른 폴더를 만들 수 있습니다. 대화 기록만은 AI에게 묻지 않고 원본 대화를 저장합니다.
  3. 노트에서 이어서 작업 — 노트를 누르면 새 탭에서 이어서 작업합니다. Agentty가 저장한 요약은 작성됐던 폴더와 에이전트로 다시 열리고, 그 밖의 노트는 포커스된 페인의 폴더와 에이전트를 씁니다. 최근 노트 몇 개만 먼저 보이고(더 보기로 나머지), 검색은 전체에서 찾습니다. 행의 버튼으로 노트를 포커스된 터미널에 넣거나, **다른 곳에서 이어가기…**로 위치를 고릅니다.
  4. Cosmica에서 — 노트를 우클릭 → Agentty에서 계속하기. 노트가 새 탭에 입력된 상태로 열립니다. 읽어 보고 Enter를 누르면 시작합니다.

아직 작업 중인 에이전트는 요청을 대기열에 넣어 두었다가 턴이 끝나는 대로 요약을 씁니다. 답변이나 승인을 기다리는 에이전트는 건드리지 않습니다. Cosmica가 실행 중이면 로컬 API로 저장해서 바로 색인됩니다. 실행 중이 아니면 파일로 써 두고, Cosmica가 다음에 실행될 때 가져갑니다.

문제가 생기면#

증상조치
"Node.js를 찾을 수 없음"JavaScript 플러그인은 로그인 셸의 PATH에 Node.js 18 이상이 필요합니다. WebAssembly 플러그인은 설치할 것이 없습니다
마켓플레이스 설치가 거부됨모듈이 목록의 체크섬과 일치하지 않았습니다. 아무것도 기록되지 않았으니 제작자에게 알리세요
카드에 최신 Agentty가 필요하다고 표시됨이 버전이 모르는 플러그인 프로토콜로 만들어진 플러그인입니다. Agentty를 업데이트하세요
카드에 오류로 중단됐다고 표시됨카드의 로그를 열어 확인하고, 코드를 고친 뒤 재시작
복사해 넣은 플러그인이 보이지 않음새로 고침을 누르고, 폴더 이름이 agentty-plugin.json의 id와 같은지 확인
링크가 아무 반응이 없음설치된 애플리케이션을 쓰고, 링크가 지정한 플러그인이 설치·활성화돼 있는지 확인
업데이트 후 동작이 이상함재시작하거나 비활성화하고 제작자에게 문제를 알리세요

파일 위치#

경로용도
~/.agentty/plugins/<id>/플러그인 본체
~/.agentty/plugins/state.json활성화 상태와 개발용 연결 위치
~/.agentty/plugin-data/<id>/플러그인의 설정과 캐시
~/.agentty/plugins/.sdk/개발자 가이드가 풀어 놓는 SDK와 문서
~/.agentty/prompts/파일로 전달되는 긴 프롬프트

삭제하면 플러그인은 제거되지만 데이터 폴더는 직접 지울 때까지 남습니다.

다음으로#