에이전트 CLI 프레임워크

aclif은 AI 에이전트를 위한 커맨드라인 도구를 구축합니다. 에이전트는 모든 SaaS 제공업체에 걸쳐 통합 추상화를 제공하는 단일 도구를 얻게 됩니다: 즉, 하나의 문법과 어떤 플랫폼에서든 동일한 이름으로 같은 레코드에 도달할 수 있는 표준화된 이름입니다.

지금 사용해 보기

바이너리를 설치하고, 제공업체를 나열하며, 명령어의 스키마, 예시 및 안전 메타데이터를 읽어보세요.

npm install -g @aclif/core
aclif discover --json
aclif learn salesforce --json
...

에이전트가 자체 CLI를 필요로 하는 이유

MCP 서버는 고정된 도구 목록을 게시하며, 이 목록의 모든 도구는 턴마다 에이전트의 컨텍스트를 차지합니다. 서버 작성자는 비용을 위해 커버리지를 희생할 때가 있습니다. 모든 작업을 게시하는 것(일반적인 API는 수백 개의 정의를 가집니다)은 전체 API에 접근 가능하게 유지하지만, 매 턴마다 그 모든 것에 대한 토큰을 소모합니다. 몇 가지 광범위한 작업만 게시하면 토큰 수가 작게 유지되지만, 작성자가 목록에서 제외한 어떤 작업이든 에이전트의 범위를 벗어납니다. 여러 플랫폼에 걸쳐 작동하는 에이전트는 서버, 로그인, 문법, 오류 형식 및 각 항목에 대한 이름 세트를 필요로 합니다.

aclif은 에이전트가 요청할 때만 명령어 정의를 로드하므로, 모든 제공업체의 전체 API가 컨텍스트 내에서 아무런 기본 비용 없이 접근 가능합니다. 하나의 문법, 하나의 엔벨로프(envelope), 그리고 하나의 오류 어휘가 모든 제공업체를 포괄하여, 에이전트의 컨텍스트 크기는 한 플랫폼에 도달하든 다섯 개 플랫폼에 도달하든 거의 동일하게 유지됩니다.

작동하는 정의된 워크플로우를 가진 에이전트는 모델을 호출에서 완전히 제외할 수 있습니다. 사람이나 작성 도구가 설계 시간에 정확한 명령어를 계산하여 이를 문자열로 워크플로우에 임베드합니다. 실행 시점에 에이전트는 이 문자열을 일반 코드로 실행하며, 도구 정의가 로드되거나 추론 과정이 필요하지 않습니다. 명령어는 설계 시간에 선택되며, 이를 실행할 권한, 자격 증명, 동작하는 신원(identity), 정책은 실행하는 주체에 의해 실행 시점에 제공됩니다. 어느 쪽도 이 두 가지를 모두 보유하지 않습니다.

모든 명령어가 제공하는 것

하나의 문법

모든 제공업체에서 단일 명령어 구조, 단일 JSON 엔벨로프, 그리고 단일 오류 어휘를 사용합니다. 에이전트는 도구를 한 번 학습하고, 새로운 플랫폼은 문법을 추가하지 않고도 명령어를 추가할 수 있습니다. JSON 매니페스트는 코딩 없이 하나의 HTTP 엔드포인트에 명령어를 추가합니다.

표준 이름 (Canonical names)

별칭 세트(Alias sets)는 한 Salesforce 인스턴스에서는 customer를 Account로, ServiceNow에서는 core_company로 매핑합니다. 배포 시 각 인스턴스에서 캡처된 테넌트 카탈로그는 CLI에게 제공업체에 변경을 가하지 않으면서도 각 인스턴스의 사용자 정의 객체와 필드를 학습시킵니다.

에이전트가 처리할 수 있는 오류 (Errors an agent can act on)

에이전트는 한 번의 턴(turn) 만에 복구합니다. 모든 오류는 실패를 명명하고, 이를 수정하는 명령어, 그리고 제공업체의 분류기(classifier)가 실수에 대한 재작성 규칙을 가지고 있다면 다시 전송할 준비가 된 수정된 입력을 알려줍니다. 이 분류기는 모델 기반이 아닌 순수 코드입니다. 설계 시 셸에서 검증된 명령어는 동일한 명령어 클래스가 양쪽에서 실행되기 때문에, 어떤 호스트에서도 실행 시 동일한 오류를 반환합니다.

실행 없는 내부 조사 (Introspection without execution)

--schema, --examples, --shape, 그리고 네 개의 추가 플래그들은 명령어가 실행되기 전에 반환되며, 자격 증명이 필요 없고 API 할당량에 포함되지 않습니다. 에이전트는 속도 제한이 걸린 인스턴스에 대해서도 발견하고, 학습하고, 내부 조사하며, 미리 볼 수 있으며 비용을 전혀 지출하지 않습니다.

임베디드 런타임 (An embeddable runtime)

동일한 명령어 클래스는 자격 증명, 신원(identity), 요청별 정책을 제공하고, 연결을 따뜻하게 유지하며, 인스턴스별로 비용이 많이 드는 로그인을 캐싱하는 호스트 내부에서 실행됩니다. 이를 기반으로 구축된 게이트웨이는 기업 자체의 ID 공급자 및 비밀 저장소와 작동합니다.

선언된 안전성 (Declared safety)

가변성(Mutability), 폭발 반경(blast radius), 가역성(reversibility), 그리고 **멱등성(idempotency)**은 모든 명령어에 대해 선언됩니다. 정책 검사(policy check)는 코드가 로드되기 전에 이를 거부할 수 있습니다. 모든 변경 사항은 --dry-run을 받아들이고, 메타데이터가 그렇게 요구하는 경우 --confirm를 요구하며, 실행 후마다 감사 라인(audit line)을 작성합니다.

내부 조사 우선 워크플로우 (The introspection-first workflow)

에이전트는 바이너리 외에는 문서가 필요 없으며, 마지막 단계에서 API를 건드리기 전까지는 아무것도 필요하지 않습니다.

aclif discover --json # 모든 프로바이더, 티어, 자격 증명 설정 여부
aclif learn salesforce --json # 브리핑: 토픽, 주요 필드, 쿼리 구문, 인증 경로
aclif salesforce data query --schema # 플래그, 인자, 안전 메타데이터, 실행 없음
...

엔벨로프의 _context 블록은 정확한 다음 명령어, 사용 가능한 필드, 그리고 실행할 가치가 있는 관련 명령어를 포함하는 페이지네이션을 담고 있습니다. 종료 코드는 0, 1(API), 2(사용법), 3(인증)입니다. 계약 및 해당 JSON Schema는 CONTRACT.md에 있습니다.

세 가지 실행 방식

벤더 CLI는 하나의 배포를 위해 구축됩니다: 기계에 설치되고, 키보드 앞의 사람이 로그인하며, 명령어당 하나의 프로세스가 발생합니다. 실패하는 게이트웨이 뒤에 있습니다. 모든 호출은 프로세스를 생성하고 다시 로그인하므로, 동작하는 사용자의 신원을 전달할 수 없고, 어떤 것도 명령어가 무엇을 할지 선언하지 않으며, 감사하기 위해 통일된 것이 없습니다. aclif의 명령어 클래스는 세 곳에서 변경 없이 실행되며, 누가 이를 실행하는지에 따라 자격 증명을 제공하고, 정책을 강제하며, 감사 추적을 유지할지 결정합니다.

에이전트가 실행하는 경우. 에이전트 프로세스가 바이너리를 생성하고 명령을 실행한 다음 반환되는 JSON을 읽습니다. 자격 증명은 플래그, 환경 변수 또는 에이전트 자체 환경의 프로필에서 가져옵니다. 하나의 에이전트, 하나의 운영자, 그리고 하나의 자격 증명 세트가 신뢰 경계를 공유할 때 사용합니다.호스트 애플리케이션에 의해 실행되는 경우, 디자인 타임 사례. 애플리케이션은 모델과 aclif 사이에 위치하며 자격 증명을 보유합니다. 모델은 애플리케이션이 정의한 도구를 호출하고, 애플리케이션은 인프로세스(in-process)로 명령을 실행하거나 CLI에 명령 문자열을 전달하여 실행합니다. 사람이나 작성 도구가 이를 사용하여 모델이 공급자를 발견하고, 명령을 검사하며, 에이전트에 기록할 정확한 명령을 유효성 검사하도록 할 수 있습니다. 모델이 절대 자격 증명을 보유해서는 안 되고 도구 정의가 컨텍스트 밖에 있어야 할 때 사용합니다.게이트웨이에 의해 실행되는 경우, 런타임 사례. 배포된 에이전트가 명령을 제출하고, 하나의 장기 실행 프로세스가 많은 이러한 에이전트를 서비스합니다. 게이트웨이는 요청별로 엔터프라이즈 볼트에서 자격 증명을 확인하고, 동작하는 사용자에게 정책을 검사하며, 모든 호출을 기록하고, 연결을 따뜻하게 유지합니다. 에이전트는 공급자 자격 증명을 보유하지 않으며 자신의 범위를 확장할 수 없습니다. 많은 에이전트가 공급자를 공유하고 한 곳에서 정책 및 감사를 처리해야 할 때 사용합니다.**

Embedding 페이지의 자세한 내용 참조.

게이트웨이 배포 (Gateway deployments)

오랫동안 유지되는(Long-lived) 임베드 가능한 배포는 추가적인 보안 정책을 적용할 수 있는 게이트웨이 토폴로지(gateway topology)를 가능하게 합니다. 기업이 운영하는 하나의 프로세스가 모든 에이전트의 모든 명령을 실행하며, 이 구성은 다음을 제공합니다:

한 곳에 저장된 자격 증명. 요청별로 엔터프라이즈의 볼트 내부에서 게이트웨이에 의해 해결됩니다. 에이전트는 아무것도 보유하지 않습니다.
엔터프라이즈 전체 표준 이름. 테넌트 카탈로그 및 별칭 세트는 게이트웨이가 보유하므로, 모든 에이전트는 모든 제공업체와 인스턴스에 걸쳐 동일한 레코드에 대해 동일한 이름을 사용합니다.
사람에게 귀속되는 모든 호출. 실행하는 사용자(acting user)의 신원이 정책 검사 및 감사 기록을 거치면서 공유 서비스 계정을 통해서도 각 호출과 함께 전달됩니다.
정책은 한 번 적용됨. 모든 명령은 자신이 무엇을 할지 선언하고, 게이트웨이는 명령 코드가 로드되기 전에 그 선언을 확인합니다. 에이전트는 자체 범위를 확장할 수 없습니다.
하나의 감사 추적. 사용자, 명령, 결과를 명시하는 모든 에이전트의 모든 명령에 대한 동일한 이벤트입니다.

설치하거나 직접 구축하기

npm install -g @aclif/core
# 귀하의 조직 My Domain URL (후행 슬래시 없음)
export SF_INSTANCE_URL=https://example.my.salesforce.com
...

Salesforce CLI 없이 사용할 경우, API 사용자를 사용하십시오. Salesforce는 비밀번호가 설정되거나 재설정될 때 보안 토큰을 이메일로 보냅니다:

export SF_INSTANCE_URL=https://example.my.salesforce.com [email protected] SF_PASSWORD=... SF_SECURITY_TOKEN=...
aclif salesforce data query --query "SELECT Id, Name FROM Account LIMIT 3" --json

aclif 바이너리는 모든 내장 제공업체와 함께 배포되며 Node 22 이상이 필요합니다. 귀하가 배포하는 바이너리는 귀하의 것이며, 하나의 스캐폴드(scaffold) 명령은 자체 이름, 자체 구성 디렉터리, 자체 환경 변수 및 선택한 제공업체만 포함하는 CLI를 생성합니다. 시작하기(Getting started)와
CLI 구축하기(Build a CLI)를 참조하십시오.

제공업체 (Providers)

Salesforce, ServiceNow, DocuSign, 그리고 Agentforce는 네이티브로 포함되며 모든 릴리스에 포함됩니다. Google Workspace(Gmail, Calendar)는 기여됩니다. 프라이빗 티어는 공급자가 자신만을 위해 포크하여 유지하는 곳이며, 상위 스트림에서는 절대 커밋하지 않는 경로 아래에 있습니다. 공급자를 작성하는 것은 노력이 거의 들지 않습니다. 이는 플랫폼의 API 사양을 명령어 표면(command surface)으로 직접 번역하는 것이며, 코딩 에이전트가 저장소 내 샘플 프롬프트로부터 이를 수행하고, 컨포먼스 스위트(conformance suite)가 결과를 확인합니다. 공급자 보기(See Providers).

aclif은 MIT 라이선스를 따릅니다. 기여는 CONTRIBUTING.md를 따르며, 프레임워크를 변경하는 사람과 코딩 에이전트를 위한 가이드는 AGENTS.md입니다.