더 똑똑한 에이전트를 실행하세요. 토큰 사용량을 줄이세요.
빠른 시작 · 투어 · 템플릿 · 배포 · 문서
AgentRun은 에이전트를 강력하게 만드는 오픈 소스 플랫폼입니다. 사용자가 선호하는 에이전트 하니스(agent harness) 위에 자체 개선 기능, 내구성 있는 실행(durable execution), 그리고 제어 평면(control plane)을 추가합니다. 이제 에이전트는 매번 실행할 때마다 더 똑똑해지고, 오류에 강하며, 토큰 사용량이 줄어듭니다.
An agent's Learning tab in the AgentRun console: since it learned, answers take 2 seconds instead of 10 and a run costs $0.0077 instead of $0.05, with the two notes it kept
에이전트의 학습(Learning) 탭: 무엇을 유지했고, 무엇이 변경되었는지 보여줍니다. 콘솔에 기록된 피처(fixtures)의 데모 데이터입니다.
에이전트는 문제를 해결하는 데 탁월합니다. 문제는 같은 일을 반복해서 알아낸다는 것입니다. 에이전트에게 백 번 수행한 작업을 맡기면, 동일한 API를 재발견하고, 동일한 문서를 다시 읽고, 동일한 계획을 재구축하게 되며, 이 모든 토큰에 대해 비용을 지불해야 합니다.
에이전트를 가장 잘 작동하는 하니스(harness)에서 사용하세요: Claude Code, Codex, OpenCode 또는 pi. AgentRun은 그 주변의 모든 것을 처리합니다:
작업을 학습합니다. 각 실행 후, 에이전트는 다음에 도움이 될 것들—메모, 스킬, 또는 루프 없이 작업을 수행하는 워크플로우(workflow)—을 유지합니다. 다음 실행은 그 지점부터 시작됩니다.
실행 기록을 잃지 않습니다. 모든 실행은 하나의 저장소에 존재합니다. 서버가 실행 도중에 중단되더라도, 다시 시작하면 해당 실행이 계속 진행됩니다. 에이전트에게 필요한 컴퓨터를 제공하세요: 샌드박스(sandbox), Linux 데스크톱, Android 휴대폰 또는 브라우저.
사용자가 제어권을 유지합니다. 승인(Approvals), 지출 한도(spend caps), 그리고 에이전트별 콘솔: 무엇이 사용자를 필요로 하는지, 무엇이 실패했는지, 무엇이 실행 중인지, 그리고 비용은 얼마였는지를 보여줍니다.
파이프라인(plumbing)을 직접 구축할 필요가 없습니다: 제공자 통합(provider integrations), 복구(recovery), 실행 추적(run tracking), 그리고 학습 기능은 모두 여기에 포함되어 있습니다. 하나의 명령으로, 하나의 컨테이너에서, 또는 러너(runners)를 갖춘 서버로 노트북에서 실행할 수 있습니다. Apache-2.0 라이선스입니다.
macOS 또는 Linux 환경에서 Node 24.22.3 이상이 필요합니다.
시작하기.
npx @parcha/agentrun
서버와 러너를 포트 7340(또는 다음 사용 가능한 포트)에 시작하고, 모든 것을 ~/.agentrun에 보관하며, 브라우저에서 콘솔을 엽니다.
모델 키 추가하기.
콘솔에서 비밀번호를 설정한 다음, Settings → Model keys 아래에 키를 추가합니다. 하나의 OPENROUTER_API_KEY
모든 하네스(harness)에 모델을 제공합니다. Anthropic 키는 pi와 Claude Code를 실행하며, OpenAI 키는 pi, Codex 및 OpenCode를 실행합니다.
첫 에이전트 실행하기. **템플릿(Templates)**을 열고 **KYB 실사(due diligence)**를 적용하여 회사 이름과 웹사이트로 실행을 시작할 수 있습니다. 모델 키만 있으면 됩니다. 완료되면, 실행의 리포트(Report) 탭에서 판정 및 인용된 모든 주장이 포함된 실사 보고서를 확인할 수 있습니다. 그런 다음 에이전트의 학습(Learning) 탭을 열어 다음에 무엇을 보존했는지 확인하세요.
차라리 코딩 에이전트가 처리하도록 할까요? 다음과 같이 지시할 수 있습니다: agentrun.ai/SKILL.md를 읽고 저를 위해 AgentRun을 설정해 주세요
Docker, 샌드박스 및 서버에서 실행하기
만약 로컬 컴퓨터에 Docker가 실행 중이라면, 새로운 에이전트는 셸(shell)을 갖춘 Docker 샌드박스를 받습니다. 이미지는 첫 사용 시 빌드되며 몇 분 정도 걸리고, 콘솔에서 준비 완료 시점을 알려줍니다. Docker 없이도 에이전트는 파일을 읽고 쓸 수 있지만, 셸은 제공되지 않습니다.
URL을 가진 자체 서버를 원하시나요? 클릭 한 번으로 Render에 배포할 수 있습니다.
워크플로우(Workflows)가 호출합니다. 단계는 빠르게 입력된 질문을 하고, 답변의 확신도를 확인하며, 경로를 선택할 수 있습니다. 여기서는 모델이 0.61로 승인을 기울였고, 이는 워크플로우의 0.75 기준치보다 낮아 해당 사례가 검토(review)로 넘어갑니다.
모든 에이전트를 한 곳에서. Mission Control을 먼저 열어보세요. 무엇이 필요한지, 무엇이 실패했는지, 무엇이 실행 중인지, 그리고 날짜별, 하네스별, 도구별 비용이 얼마였는지를 알 수 있습니다.
모든 에이전트는 API입니다. Playground에서 실행을 시작한 다음, 동일한 요청을 코드로 복사하세요.
사용자가 통제합니다. 에이전트는 멈춰서 사용자에게 물어볼 수 있으며, 답변할 때까지 실행은 대기합니다.
에이전트 정의에 `
**메모(Notes)**는 Claude Code의 메모 형식으로 작성된, 각기 하나의 사실만을 담은 짧은 마크다운 파일입니다. **기술(Skills)**은 작업을 다시 수행하는 방법이며, 오직 해당 작업을 완료한 실행(run)만이 기술을 작성할 수 있습니다. **학습된 워크플로우(Learned workflows)**는 어떤 시스템에서도 단일 도구 호출로 실행되며, 해당 실행 자체의 권한과 도구 권한 내에서 작동합니다. 학습된 기술이 3번의 실행에 사용되면, 다음 실행에서는 이 작업이 워크플로우 초안으로 요청되며, 실제로 모델을 요청하거나 도구를 실행하지 않은 상태에서 초안이 드라이런(dry-run)됩니다.
에이전트의 학습(Learning) 탭에는 모든 메모, 기술 및 워크플로우와 변경 로그가 표시되며, 각 실행은 어떤 메모를 받았고 열었는지 보여줍니다. 이곳의 내용을 폐기하거나 npx @parcha/agentrun learning retire 명령어를 사용하여 메모의 ETag 값을 폐기할 수 있습니다. Git이 기록을 보존하므로, 폐기된 메모도 복구될 수 있습니다.
무엇이 유지되고, 무엇이 삭제되는가
각 에이전트는 학습 폴더를 가지며, 이는 main이라는 하나의 브랜치만 있는 일반적인 git 저장소입니다. 실행은 자신의 지침(instructions)에서 활성 메모의 인덱스를 읽고, 자신만의 기술 외에 학습된 기술들을 함께 받습니다. 코드(Code)는 모든 제안을 먼저 검사합니다. 자체 규칙(크기 또는 개수 제한, 이름, 형태 등)을 위반하는 항목은 제외되고 나머지는 진행됩니다. 답변 내 어느 곳에 있는 비밀 정보나 숨겨진 문자, 폴더 외부의 파일, 삭제 행위 또는 전체 인덱스는 신뢰할 수 있는 항목이 하나도 없으므로 전체 답변을 폐기합니다. 그 후 한 개의 평가자(grader)가 내용을 판단하고 AgentRun은 통과된 내용만 커밋합니다. 위험한 규칙은 사용자의 승인을 기다립니다. 실행이 페이지나 붙여넣은 이메일에서 발견했거나, 계좌 번호를 담고 있는 메모와 같은 규칙은 폐기됩니다.
에이전트의 메모가 학습 예산을 초과하면, 각 실행에는 첫 번째 메시지와 관련된 모든 메모 전체와 나머지 메모 각각에 대한 한 줄씩만 제공됩니다. 오직 학습된 워크플로우만을 실행한 경우에는 무엇을 유지해야 하는지 요청받지 않습니다.
많은 에이전트가 반드시 에이전트일 필요는 없습니다. 반복 가능한 작업은 타입 지정된 워크플로우(typed workflow)로 작성할 수 있습니다. 여기에는 도구 호출(tool calls), 모델 단계(model steps), 그리고 빠른 타입 질문(예/아니오, 하나 선택, 점수 등 각 항목에 신뢰도 포함)이 포함되며, 케이스가 불분명할 때 폴백(fallback) 할 에이전트만 추가하면 됩니다. AgentRun은 이를 에이전트의 개정판(revision)으로 실행하며, 해당 에이전트의 도구 권한과 모든 실행에 적용되는 제한을 따릅니다. 또한 트리거를 통해 이 워크플로우를 시작할 수 있습니다.
Support workflow: search for an answer, check it with Jev, and return it or ask an agent to investigate
이는 examples/support-answer.mjs에서 제어 흐름(control flow)을 보여주는 예시일 뿐, 모델 실행 기록은 아닙니다.
워크플로우가 노드별로 어떻게 실행되는지 확인하고, 일시 중지했다가 다시 시작하며, 모든 결정과 그 이유를 읽어볼 수 있습니다:
워크플로우의 구조
워크플로우는 타입 지정된 단계(typed steps)들의 JSON 문서입니다:
{
"v": 2, "name": "read-site",
"schemas": {
...
단계들은 도구를 호출하거나, 모델을 실행하거나, 빠른 타입 질문을 하거나, 답변에 따라 분기(branch)할 수 있고, 리스트를 병렬로 매핑(map over a list in parallel)하거나, 제한된 횟수만큼 반복(loop)할 수 있으며, 다른 워크플로우를 호출하거나, 어려운 케이스는 에이전트에게 맡길 수도 있습니다. 이 중 하나를 에이전트의 workflow 필드로 저장하면 됩니다. npx @parcha/agentrun workflows validate 명령어로 먼저 검증합니다. 또한 이 워크플로우 언어는 TypeScript 빌더와 함께 앱 내부에서도 자체적으로 실행됩니다.
모든 에이전트, 개정판(revision), 실행(run), 그리고 단계(step)는 하나의 스토어에 저장됩니다. 서버를 실행 도중에 중단했다가 다시 시작해도 해당 실행은 계속 진행됩니다. 여러 러너(runner)를 사용할 경우, 30초의 임대 시간이 만료되면 다른 러너가 죽은 러너의 실행을 이어받습니다. 완료된 단계는 다시 실행되지 않으며, 호출 중간에 발생한 충돌(crash)은 재시도되는 대신 '중단됨(interrupted)'으로 표시되어 사용자가 확인할 수 있습니다.
승인(Approvals). 각 도구는 허용되거나, 먼저 사용자에게 요청하거나, 거부될 수 있습니다. 요청하는 호출은 사용자가 답변할 때까지 실행 페이지에서 대기합니다. '절대 묻지 않음(Never ask)'을 설정하면 에이전트가 감독 없이 실행될 수 있으며, 서버에 설정된 거부는 여전히 효력을 가집니다.지출 한도(Spend caps). 실행에 한도를 부여하면 실패하는 대신 거기서 일시 중지되며, 최소한으로 필요한 비용을 알려줍니다. AgentRun은 비용을 산정할 때 '알 수 없음(unknown)'을 반환하며, 절대 $0이 아닙니다.질문(Questions). 에이전트는 멈춰서 사용자에게 질문할 수 있으며, 실행은 사용자가 답변할 때까지 대기합니다.단일 콘솔(One console). 각 실행에는 실시간 타임라인(Timeline)과 파일, 그리고 브라우저의 경우 사용자가 제어할 수 있는 화면이 있습니다.
다섯 가지 준비된 에이전트가 있습니다. 한 화면에서 하나를 적용하고 자신만의 것으로 만들고 자체 평가 케이스로 측정해 보세요. 각 템플릿은 하나의 폴더입니다: 에이전트의 지침, 기술(skills), 규칙, 그리고 평가 케이스가 포함되어 있습니다. **'템플릿 → 적용(Templates → Apply)'**을 사용하더라도 MCP 도구 각각에 직접 체크하지 않으면 아무것도 부여되지 않습니다.
| 템플릿 | 기능 |
|---|
code-review | 풀 리퀘스트 또는 diff를 검토하고, 각 발견 사항을 코드와 비교하여 JSON 형식으로 결과를 반환합니다. 자체 GitHub 트리거를 설정합니다. |
kyb | 한 회사에 대한 실사(due diligence): 등록소, 소유주, 제재 목록, 날짜가 지정된 부정적 언론 보도 및 모든 주장마다 인용된 판결을 제공합니다. |
market-monitor | 매주 월요일, 사용자가 주시하는 회사들의 변경 사항 요약본을 제공하며, 각 항목은 날짜가 지정되고 링크되어 있습니다. |
inbound-lead | 웹훅(webhook)이 전송하는 각 리드를 조사하고 이상적인 고객 프로필 대비 0점에서 100점까지 점수를 매깁니다. |
release-notes | 마지막 릴리스 이후 병합된 풀 리퀘스트를 릴리스 노트로 변환하여 담당자에게 초안 이슈(draft issue) 형태로 남깁니다. |
npx @parcha/agentrun template eval DIR
명령어는 템플릿의 평가 케이스를 임시 서버에서 실제 실행처럼 구동하고 점수를 매깁니다. 템플릿 패키지는 폴더 형식을 가집니다.
**트리거(Triggers)**는 자체적으로 제한된 실행을 시작합니다: 스케줄, 서명된 웹훅, 그리고 GitHub 풀 리퀘스트 이벤트입니다.
하네스(Harnesses). 에이전트 정의 내에서 harness를 사용하여 이름을 지정할 수 있습니다. 승인, 한도, 컴퓨터, 트리거 및 학습은 각각에 대해 동일하게 작동합니다. npx @parcha/agentrun server capabilities
서버가 실행하는 하네스(harness)를 명시합니다.
| Harness | harness | Notes |
|---|
| pi | pi | 기본값 (The default) |
| Claude Code | claude-agent | 첫 사용 시 자체 설치됨 (Installs itself on first use) |
| Codex | codex | 첫 사용 시 자체 설치됨 (Installs itself on first use) |
| OpenCode | opencode | 서버 옆에 opencode-ai 패키지가 필요하며, AgentRun이 이를 설치하는 줄을 출력합니다. |
컴퓨터(Computers). 에이전트는 하나의 설정으로 컴퓨터를 얻습니다. 해당 종류에 맞는 도구만 제공받으며 다른 것은 아무것도 받지 않으며, 컴퓨터를 변경해도 에이전트의 다른 부분은 전혀 변하지 않습니다.
computer:
kind: sandbox # none, sandbox, desktop, phone or browser
provider: daytona # Settings → Computers에서 연결한 것 중 하나 (none은 제공업체가 없음)
| Kind | 에이전트가 할 수 있는 작업 | Providers |
|---|---|
none | 실행 폴더 내 파일 읽기 및 쓰기; 셸(shell) 없음 (Archil의 경우, 명령은 Archil의 exec에서 실행됨) | 제공업체 불필요 (none needed) |
sandbox | 코드 실행, 패키지 설치, 프로세스 백그라운드 유지, Linux 환경 지원 | Docker, Daytona, Modal, E2B |
desktop | Linux 화면 보기, 마우스 이동, 타이핑 가능 | Orgo, E2B, Docker (X 서버가 있는 자체 이미지) |
phone | Android에서 탭, 스와이프, 타이핑, 앱 열기 및 화면 읽기 | phone harness (임대된 클라우드 Android) |
browser | 웹 브라우징, 원하는 시점에 제어권을 사용자에게 넘겨줌 | Browserbase, Kernel |
none을 제외한 모든 종류는 제공업체(provider) 이름을 명시합니다. 컴퓨터 설정이 없는 에이전트는 서버에 Docker가 있는 경우 Docker 샌드박스를 얻으며, 그렇지 않은 경우에는 컴퓨터를 갖지 않습니다. 원격 컴퓨터는 공급업체와 직접 귀하의 계정을 통해 청구됩니다.
키(Keys). 판매자(vendor)의 키를 **설정(Settings) → 컴퓨터(Computers)**에 한 번 추가합니다. 서버가 이를 봉인하여 설정됨 또는 누락된 상태로만 표시하며, 에이전트의 컴퓨터 내부에는 절대 들어가지 않습니다.
**연결 테스트(Test connection)**는 판매자 측에서 읽기 작업을 수행할 뿐 아무것도 시작하지 않습니다.
실행 파일(The run's files). 기본적으로 실행 폴더는 서버에 존재하며 Docker 샌드박스스가 이를 마운트합니다. 설정에서 Archil 디스크를 활성화하면 해당 폴더가 그곳에 존재하게 되어 Daytona, Modal 또는 E2B 샌드박스도 동일한 폴더를 마운트할 수 있습니다. 이 세 가지는 Archil 디스크로만 실행되며, Docker 샌드박스에서 Archil을 사용하는 것은 거부됩니다.
모니터링 및 제어권 인수(Watching and taking over). 브라우저 실행은 판매자 링크를 통하는 것이 아니라 사용자의 자체 서버를 통해 실행의 화면(Screen) 탭으로 스트리밍됩니다. 제어권을 가져간 다음 다시 넘겨줄 수 있습니다. 에이전트는 로그인이나 캡차(captcha)가 필요할 때 중지하고 사용자에게 인수를 요청할 수도 있습니다.
증명(Proof). 각 제공업체는 해당 유형에 맞는 적합성 테스트 스위트(conformance suite)를 가지고 있습니다. 다음 명령을 통해 직접 판매자 측에서 실행해 보세요: npm ci && npm run build 이후의 체크아웃에서
:`npm run conformance -w @parcha/agentrun-computer -- --provider docker --kind sandbox`
@parcha/agentrun-computer는 아래의 프로토콜입니다. 모든 컴퓨터에 작은 데몬(daemon) 하나와 판매자당 하나의 제공업체가 있습니다.
flowchart LR
you["Console · CLI · API"] --> server["Server"]
server --> store["One store<br/>SQLite or Postgres"]
...
서버(Server). /v2에서 API와 콘솔을 제공합니다. 실행 기록과 명령을 스토어에 쓰고 사용자에게 다시 읽어옵니다. --no-runner로 시작할 경우 자체적으로 에이전트 루프를 실행하지 않습니다.
