eve extension을 버전이 있는 능력 경계로 설계하기
eve의 tool, connection, skill, instruction, hook을 package로 묶으면서 namespace, secret, approval, runtime policy, upgrade 위험을 통제하는 방법을 설명합니다.
재사용 가능한 에이전트 코드는 보통 파일 복사에서 시작합니다. tool 하나, SKILL.md 하나, connection 하나, audit hook 하나를 다른 프로젝트에 복사합니다. 첫 복사는 저렴하지만 다섯 번째 복사는 version, permission, security 문제가 됩니다.
eve extension은 tool, connection, skill, instruction, hook을 하나의 installable dependency로 package합니다. 유용한 경계는 “재사용할 수 있는 코드”가 아닙니다. 소비하는 에이전트가 검사하고 제한하고 제거할 수 있는 버전이 있는 능력·권한 계약입니다.
Vercel은 2026년 7월 22일 installable eve extension을 발표했습니다. 공개 eve changelog는 mounted extension과 그 ownership·peer-range contract를 0.22.4에 기록하고, 전용 eve extension init과 eve extension build command는 0.22.5에 추가합니다. 8월 5일 조사 cutoff에서 npm은 eve 0.30.8을 표시했고 mounted extension은 계속 지원됐습니다.
복사한 folder가 아니라 능력 경계를 package합니다
실제 에이전트 능력은 함수 하나보다 넓습니다.
CRM capability
├─ connection and authentication contract
├─ read tools
├─ write tools
├─ task-specific SKILL.md
├─ shared instructions
└─ audit and redaction hooks일반 library는 HTTP client와 schema를 공유할 수 있지만 각 consumer가 agent-facing 부분을 다시 등록해야 합니다. extension은 구성 요소를 함께 배포하고 하나의 namespace 아래 mount합니다.
| 배포 선택 | 적합한 경우 | 운영 경계 |
|---|---|---|
| 파일 복사 | 짧은 실험 하나 | 공유 upgrade 또는 provenance 경로가 없음 |
| 일반 npm library | 순수 함수와 SDK client | consumer가 agent capability를 직접 연결 |
| MCP server | remote, cross-language tool | network, service, authentication 운영이 추가됨 |
| eve extension | eve agent 사이의 재사용 능력 | eve package와 mount contract를 따름 |
MCP와 extension은 함께 사용할 수 있습니다. extension은 connection, 사용 지침, tool 주변의 local hook을 package할 수 있습니다. extension이 remote service의 authorization 필요성을 없애지는 않습니다.
extension이 소유할 수 있는 범위를 압니다
extension 경계는 의도적으로 전체 agent보다 좁습니다. 공개 eve changelog에 따르면 extension은 tool, connection, skill, instruction, hook, library, extension-scoped state를 제공할 수 있습니다.
다음은 선언할 수 없습니다.
- agent configuration
- sandbox
- schedule
- runtime limit
- 또 다른 nested extension
이 통제는 consuming agent에 남습니다. 따라서 reusable capability package가 runtime-wide isolation 또는 resource policy를 조용히 교체하지 못합니다.
eve는 peer dependency이기도 합니다. extension을 mount할 때 선언된 peer range를 검사하므로 runtime compatibility는 늦은 실행 오류가 아니라 명시적인 package constraint가 됩니다.
package를 scaffold하고 build합니다
공식 CLI로 extension project를 만들 수 있습니다.
npx eve@latest extension init crm생성된 package는 agent와 비슷한 convention을 따릅니다.
@acme/crm/
├─ package.json
└─ extension/
├─ extension.ts
├─ tools/
├─ connections/
├─ skills/
├─ instructions.md
├─ hooks/
└─ lib/extension.ts는 consumer configuration contract를 정의합니다. 공식 발표는 Zod 같은 Standard Schema 구현을 허용합니다.
import { defineExtension } from 'eve/extension';
import { z } from 'zod';
export default defineExtension({
config: z.object({
apiBaseUrl: z.string().url(),
readOnly: z.boolean().default(true),
}),
});capability가 준비되면 publishable package를 build합니다.
eve extension build이 명령과 configuration shape는 공식 문서와 대조했습니다. 이 글을 위해 package를 scaffold하거나 publish하지 않았습니다.
통제할 수 있을 만큼 tool을 좁게 만듭니다
search와 mutation을 한 tool에 합치지 마세요. consumer는 read를 허용하면서 write에는 approval을 요구할 수 있어야 합니다.
crm__search_contacts read
crm__read_contact read
crm__add_note write
crm__delete_contact destructive write좁은 tool은 approval prompt 이상을 개선합니다. least-privilege credential, audit event, retry, evaluation case, deprecation decision을 정의하기 쉬워집니다.
그런 다음 SKILL.md가 sequence와 judgment를 설명할 수 있습니다. 생성 전에 검색하고, identity가 모호하면 멈추고, sensitive field를 피하며, 외부 상태 변경 전에 approval을 요구합니다. tool schema는 유효한 input을 설명하고 skill은 언제 tool을 고려해야 하는지 설명합니다.
namespace를 통해 mount합니다
package를 설치하고 agent/extensions/에서 import합니다.
// agent/extensions/crm.ts
import crm from '@acme/crm';
export default crm({
apiBaseUrl: process.env.CRM_API_BASE_URL!,
readOnly: process.env.NODE_ENV !== 'production',
});filename이 namespace가 됩니다. crm.ts의 search tool은 crm__search로 나타납니다.
이 prefix에는 운영 가치가 있습니다.
- 두 package의 tool이 충돌하지 않습니다.
- log에 어떤 capability가 action을 만들었는지 표시됩니다.
- approval과 evaluation rule이 하나의 namespace를 target할 수 있습니다.
- mount를 제거하면 예측 가능한 capability set이 제거됩니다.
namespace는 isolation이 아닙니다. package를 식별할 뿐이며 credential, network policy, sandboxing, approval은 consuming agent가 계속 소유합니다.
권한과 secret은 consumer가 소유합니다
extension author는 안전한 default를 제공해야 하지만 실제 tenant, environment, risk는 consuming agent가 압니다.
공식 발표에 따르면 consumer는 extension tool 실행 전에 approval을 요구하고, local implementation으로 교체하거나, disableTool()로 제거할 수 있습니다. 이 통제를 사용해 consumer-side policy를 적용하세요.
- read-only tool을 기본 활성화합니다.
- write에는 approval을 요구합니다.
- use case에 필요하지 않으면 destructive tool을 비활성화합니다.
- audit logging 전에 sensitive input과 output을 redact합니다.
- dependency update마다 새 tool을 검토합니다.
API key를 extension default나 committed configuration에 넣지 마세요. secret이 아닌 behavior setting은 config schema로 전달하고 credential은 environment 또는 connection boundary에서 resolve합니다.
각 external service에 다음을 문서화합니다.
- 필요한 environment variable 또는 connection
- 최소 OAuth scope 또는 API permission
- user-level identity인지 shared application identity인지
- 허용된 network destination
- data retention과 log-redaction 동작
- approval 없이 실행할 수 있는 tool
agent-browser를 구체적인 경계 사례로 봅니다
유지 관리되는 @agent-browser/eve 문서는 capability package가 유용한 경계를 유지하는 방식을 보여 줍니다. agent sandbox 안에서 browser state를 실행하면서 browser tool을 namespace 아래 mount합니다.
// agent/extensions/browser.ts
import browser from '@agent-browser/eve';
export default browser({
allowedDomains: ['example.com', '*.example.com'],
maxOutputChars: 50_000,
});agent는 browser__navigate, browser__snapshot, browser__click 같은 tool을 받습니다. package는 domain restriction과 output truncation을 문서화하고 credential material을 model에 노출할 수 있는 cookie, storage, saved-auth-state command를 의도적으로 제외합니다.
이는 “package에 browser automation이 들어 있다”보다 강한 계약입니다. browser가 실행되는 위치, 허용 destination, context에 들어갈 수 있는 output 양, 빠진 sensitive ability를 명시합니다.
모든 upgrade를 권한 diff로 검토합니다
semantic versioning은 API compatibility를 설명하지만 agent authority 전체를 설명하지는 않습니다. backward-compatible release도 model이 할 수 있는 일을 바꾸는 새 tool, connection, hook, instruction을 추가할 수 있습니다.
extension upgrade를 두 축에서 검토하세요.
| 변경 | API 검토 | 권한 검토 |
|---|---|---|
| 내부 bug fix | regression risk | error handling 또는 logging이 더 많은 data를 노출하는가? |
| 새 read tool | 보통 additive | 새 dataset 또는 scope에 접근하는가? |
| 새 write tool | 보통 additive | default가 disabled 또는 approval-gated인가? |
| input-schema 변경 | breaking일 수 있음 | 더 넓은 input이 더 큰 target set에 도달하는가? |
| hook 변경 | caller에게 보이지 않을 수 있음 | 더 많은 content를 수정, 보존, 전송하는가? |
| connection-scope 변경 | type을 깨지 않을 수 있음 | authorization을 다시 받아야 하는가? |
dependency를 pin하고 lockfile을 commit합니다. update pull request에서 TypeScript compile 결과만 보지 말고 package contents와 capability diff를 검사하세요.
package와 consumer를 따로 테스트합니다
extension package는 다음을 증명해야 합니다.
- 잘못된 configuration을 거부합니다.
- tool schema와 error path가 문서대로 동작합니다.
- hook이 의도한 field를 redact합니다.
- skill과 instruction이 artifact에 포함됩니다.
- package에 source secret 또는 의도하지 않은 file이 없습니다.
- 선언된 eve peer range가 지원 runtime과 맞습니다.
consuming agent는 다음을 증명해야 합니다.
- 예상 namespace와 tool set이 나타납니다.
- write와 destructive tool에 의도한 approval rule이 있습니다.
- disabled tool을 model이 사용할 수 없습니다.
- credential이 최소 scope를 가집니다.
- sandbox와 network control을 consumer가 계속 소유합니다.
- upgrade가 대표적인 model behavior를 회귀시키지 않습니다.
type check는 바뀐 tool description 또는 skill이 만드는 모든 behavior change를 찾지 못합니다. 고위험 selection과 sequencing rule에는 scenario evaluation을 유지하세요.
권고
permission boundary와 release cadence를 공유하는 하나의 capability로 시작하세요. configuration을 typed 상태로 유지하고, secret은 외부에 두며, write는 approval-gated로 만들고, dependency를 pin합니다.
consumer가 package와 mount diff만 보고 네 가지 질문에 답할 수 있을 때 eve extension은 성공한 것입니다. 어떤 capability가 추가됐는가, 어떤 권한이 필요한가, 어디에서 실행되는가, 어떻게 제거하는가입니다.