agentenv은(는) 무엇을 하나요?
agentenv는 일반 값과 자격 증명 참조를 보관하는 로컬 TOML 구성 파일을 읽습니다. 자격 증명 값은 환경 변수, 플랫폼 자격 증명 저장소 또는 외부 명령어에 저장되며, 파일에 직접 저장되지 않습니다. CLI는 값을 읽고, 형식이 유효한 형식 보존 쓰기로 파일을 편집하고, 선택한 값을 임시 환경에 주입하여 대상 프로세스를 실행합니다.
CLI가 사용 가능한지 command -v agentenv로 확인한 후에 의존하십시오. CLI가 없으면 그 사실을 알리고 중단하십시오. 구성 파일을 직접 읽어 동작을 재구성하지 마십시오.
엄격한 규칙
- 해결된 자격 증명 값을 절대 출력, 기록, 유지 또는 요약하지 마십시오.
agentenv run을 자체 환경을 노출하도록 선택된 대상(예:env,printenv,set,sh -c 'echo $VAR'또는 환경을 파일에 쓰기)으로 실행하지 마십시오. - 구성 파일에 비밀 값을 절대 쓰지 마십시오.
set은 일반 값용입니다.credential add는 정의만 씁니다.credential set은 값을 저장하는 유일한 경로이며, 파일이 아닌 플랫폼 자격 증명 저장소에 저장합니다. - 프로필, 항목, 필드 또는 자격 증명이 누락된 경우 명시적으로 보고하십시오. 필드 이름을 추측하거나, 자동으로 프로필을 전환하거나, 다른 자격 증명을 대체하지 마십시오.
- TOML 파일을 직접 열지 말고 CLI를 통해 구성을 읽어 프로필 선택, 자격 증명 간접 참조 및 유효성 검사가 적용되도록 하십시오.
credential fill이 브라우저 필드에 값을 쓴 후에는 해당 필드를 다시 읽거나, 값을 평가하거나, 그 값을 보여주는 스크린샷을 찍지 마십시오. 채우기 결과만 보고할 수 있습니다.
구성 읽기
위에서 아래로 작업하십시오. 이 세션에서 이미 수행한 단계는 건너뛰십시오.
agentenv project status --json— 프로필 종속 구성을 읽기 전에 가장 가까운 프로젝트 파일과 신뢰 상태를 확인합니다. 종료 코드5또는6으로 종료되어도 보고서가 stdout에 기록됩니다. 종료 코드2는 stdout을 비웁니다.agentenv list --json— 프로필과 항목을 확인합니다.agentenv list --profiles는 프로필을 선택하지 않고 이름만 나열합니다.agentenv show <entry> --json— 익숙하지 않은 항목을 사용하기 전에 검사합니다. 자격 증명 필드는reference멤버(credential://<name>또는credential://<name>?as=<ENV>)로 나타나며, 값으로 표시되지 않습니다.agentenv get <path>— 하나의 일반 스칼라 값을 읽습니다. 배열이나 테이블에는--json을 사용하십시오. 자격 증명 필드를 읽으면 비밀값이 아닌 참조 문자열이 반환됩니다.agentenv find <needle> --json— 항목 이름, 필드 이름, 설명 및 문자열 값을 검색하여 특정 값의 위치를 모를 때 사용합니다. 모든 프로필을 검색하려면--all-profiles를 추가하십시오.
경로는 선택한 프로필 내에서 점으로 구분된 필드 세그먼트입니다. 예: llm.model. 구두점이나 공백이 포함된 세그먼트는 따옴표로 묶으십시오: servers."my host".port. 프로필은 경로의 일부가 아닙니다. --profile <NAME>으로 선택하십시오 (우선순위: --profile, AGENTENV_PROFILE, 신뢰된 프로젝트 파일 핀, 파일의 default_profile). 이는 읽기, run, set, unset에 적용됩니다. --create-profile은 명시적인 --profile이 필요하며 핀을 절대 사용하지 않습니다.
프로젝트 범위 구성
agentenv는 작업 디렉터리에서 파일 시스템 루트로 이동하면서 가장 가까운 일반 .agentenv.toml 파일을 찾습니다. 파일은 닫힌 선택 전용 스키마를 가집니다: version = 1, 선택적 비어 있지 않은 profile, 선택적 [requires.<entry>] 테이블(비어 있지 않은 reason 및 선택적 항목 상대 fields 포함, 존재하는 경우 비어 있지 않음). 64KiB로 제한되며 값, 자격 증명 정의, inject 테이블 또는 credential:// 문자열을 포함할 수 없습니다.
프로젝트 파일은 정확한 내용이 승인될 때까지 비활성 상태입니다. agentenv project status, agentenv project allow, agentenv project revoke를 사용하여 검사, 승인 및 승인 제거를 수행하십시오. 승인은 사용자 상태 디렉터리에 저장되며, 저장소 외부에 있습니다. 파일을 편집하면 다시 신뢰할 수 없게 됩니다. 신뢰할 수 없는 파일은 하나의 stderr 알림을 제외한 일반 명령에 영향을 주지 않습니다.
project 그룹 외부의 명령에 대해 검색을 우회하려면 --no-project 또는 비어 있지 않은 AGENTENV_NO_PROJECT를 사용하십시오. 이 우회는 project status, project allow, project revoke에는 절대 적용되지 않으며, 항상 가장 가까운 파일을 검색합니다.
project status --json은 의도적으로 stdout에 보고서를 쓰며, 프로젝트 상태를 사용할 수 없거나, 유효하지 않거나, 신뢰할 수 없는 경우 종료 코드 5를, 요구 사항이 충족되지 않거나 확인할 수 없는 경우 종료 코드 6을 반환합니다. 이는 실패한 JSON에 대한 일반적인 비어 있는 stdout 규칙의 예외입니다. 종료 코드 2는 프로젝트 파일 유효성 검사 오류를 포함한 구성 오류를 포함하며, 이 명령에 대해 stdout을 비웁니다.
자격 증명이 필요한 명령 실행
하나 이상의 --with <entry> 플래그와 -- 뒤에 대상을 사용하여 run을 사용하십시오:
agentenv run --with llm -- llm-client request
agentenv run --with llm --with kubernetes -- deploy-tool sync
각 --with 항목은 자격 증명 참조와 inject 테이블(환경 이름을 해당 항목의 일반 필드에 매핑)을 제공합니다. 자격 증명은 참조에 ?as=<ENV> 재정의가 없는 한 inject_as 이름으로 주입됩니다. 대상이 수신할 환경 이름을 확인하려면 agentenv credential list --json에서 inject_as를 읽고 agentenv show <entry> --json에서 inject 테이블과 reference 멤버를 읽으십시오.
대상의 stdin/stdout/stderr은 변경되지 않고 통과하며 종료 상태가 반환됩니다. 충돌하는 주입(하나의 환경 이름을 대상으로 하는 두 소스)은 해결 또는 실행 전에 종료 코드 4로 중단됩니다.
--pure를 추가하면 선별된 최소 환경(고정 플랫폼 기본값(PATH, HOME, 로케일, AGENTENV_* 및 유사한 프로세스 중요 이름) + 반복 가능한 --keep <NAME>으로 전달된 변수 + 주입값)으로 대상을 실행하며, 호출 셸의 다른 것은 포함하지 않습니다. 유지된 이름이 부모에 설정되지 않은 경우 stderr에 보고되며 실행은 계속됩니다. --pure는 대상의 환경만 필터링합니다. 샌드박스가 아니며 대상 내부의 중첩된 agentenv 호출은 동일한 구성을 계속 해결합니다. 자격 증명 해결은 --pure에 의해 변경되지 않습니다. command 제공자의 하위 프로세스는 전체 부모 환경을 유지합니다.
구성 쓰기
사용자가 구성을 기록하도록 요청할 때 사용하십시오:
agentenv init # 구성 파일 생성; 덮어쓰기를 거부함
agentenv set <path> <value> # 하나의 값 쓰기; 중간 테이블 생성
agentenv set <path> <value> --type int|float|bool|json
agentenv set llm.model gpt-5 --description "Default LLM." # 항목도 생성함
agentenv set <path> <value> --profile dev --create-profile "Dev profile."
agentenv unset <path> # 하나의 필드 또는 테이블 제거
모든 항목에는 설명이 필요합니다. 새 최상위 항목을 생성하려면 동일한 set에 --description이 필요합니다. 알 수 없는 프로필은 --create-profile을 명시적인 --profile과 함께 전달하지 않으면 오류입니다. 모든 쓰기는 먼저 전체 파일 유효성을 검사하고 결과가 유효하지 않으면 거부되므로, 거부된 쓰기는 파일을 바이트 단위로 동일하게 유지합니다. — 진단 내용을 보고하고 맹목적으로 변형을 재시도하지 마십시오.
유효성 검사는 token, password, secret, api_key 또는 private_key라는 이름(또는 접미사)의 문자열 필드에 일반 텍스트 값을 거부합니다. 이러한 필드는 credential:// 참조를 보유해야 합니다. 사용자가 저장할 비밀을 건네면, 이를 자격 증명으로 정의하고 저장한 후(다음 섹션) 참조하십시오.
자격 증명 관리
agentenv credential list --json # 정의 + 얕은 상태; 아무것도 해결하지 않음
agentenv credential check <name> # 하나의 자격 증명 해결; 가용성만 보고
agentenv credential add <name> --description "<text>" --provider env \
--env-var <NAME> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider keychain \
--service <service> --account <account> --inject-as <ENV>
agentenv credential add <name> --description "<text>" --provider command \
--argv <arg> [--argv <arg> ...] --inject-as <ENV>
agentenv credential set <name> --input dialog --json # 로컬 항목 열기; 결과를 기다림
새 자격 증명의 순서: credential add로 정의를 추가한 후, keychain 제공자의 경우 credential set으로 값을 저장하고, 그런 다음 항목 필드에서 credential://<name>으로 참조합니다. Env 및 command 자격 증명은 외부 시스템에서 값을 가져옵니다. credential set이 적용되지 않습니다.
로컬 keychain 항목의 경우, PTY 없이 credential set <name> --input dialog --json을 실행하십시오. 사용자에게 로컬 창에 값을 입력하고 저장하라고 지시하십시오. 명령을 실행 상태로 유지하고 완료될 때까지 기다리십시오. 여기에는 도구 세션 중단을 넘어서는 대기가 포함됩니다. 열린 창은 완료된 저장이 아닙니다. 라이브 항목 창이나 클립보드를 검사, 캡처, 읽기 또는 자동화하지 마십시오. 사용자가 거기에 값을 입력하고 확인하며, 명령은 완료 메타데이터만 반환합니다.
종속 작업은 종료 코드 0과 JSON status: "stored" 후에만 계속하십시오. status: "cancelled"는 항목이 확인된 저장 없이 종료되었음을 의미합니다. 이를 보고하고 종속 작업을 중단하십시오. status: "failed"는 비밀이 아닌 reason을 포함합니다. 진단을 보고하십시오. store-unconfirmed는 쓰기가 발생했을 수 있음을 의미하므로 이전 값이 변경되지 않았다고 주장하거나 자동으로 재시도하지 마십시오. 시작/구성 오류는 JSON이 내보내지기 전에 종료될 수 있습니다. 0이 아닌 종료 또는 누락된 결과를 실패로 처리하십시오. 이미 진행 중인 저장은 명령이 반환되기 전에 완료됩니다. 확인된 쓰기는 사용자가 해당 쓰기 중에 종료를 요청하더라도 stored를 보고합니다.
대화 상자는 agentenv가 실행 중인 시스템의 그래픽 세션이 필요합니다. 원격 또는 헤드리스 호스트에서는 해당 제한 사항을 설명하고 사용자에게 해당 호스트의 터미널에서 직접 agentenv credential set <name> --input terminal을 실행하도록 한 후 완료를 확인하십시오. Agent 소유 PTY 또는 stdin 파이프로 대체하지 마십시오. 채팅에서 값을 묻거나 argv, 환경 변수, 명령 파이프 또는 파일에 값을 배치하지 마십시오. 터미널 입력은 로컬 표시 전환을 지원하므로 화면 출력은 Agent의 도구 외부에 남아 있어야 합니다.
로컬 사용에는 keychain 또는 command 제공자를 선호하십시오. env는 환경을 상속하는 모든 프로세스에 값을 노출하므로 CI에 적합합니다.
Docker Compose 페어링
비밀 설정은 .env에 보관하십시오. 자격 증명이 필요한 프로세스에만 주입한 후 Compose가 주입된 변수를 받도록 하십시오:
agentenv run --with llm -- docker compose up
services:
app:
image: alpine:3.20
environment:
- OPENAI_API_KEY
Compose는 ${OPENAI_API_KEY} 보간도 지원합니다. 비밀이 포함된 env_file:을 사용하지 마십시오. 파일에 자격 증명을 유지합니다.
브라우저 필드에 자격 증명 채우기
구동 중인 페이지에 저장된 자격 증명이 하나의 입력 필드에 필요한 경우 credential fill을 사용하십시오. 브라우저의 디버깅 프로토콜을 통해 값을 씁니다. 사용자는 자신의 브라우저 도구로 계속 탐색하고 제출합니다.
agentenv credential fill --capabilities --json
agentenv credential fill <name> --backend cdp --endpoint http://127.0.0.1:<port> \
--page-url <exact page URL> --selector '<css of the one input>' --json
단계:
--capabilities에cdp백엔드가 사용 가능한 것으로 나열되는지 확인하십시오. 브라우저는 루프백 Chrome DevTools Protocol 엔드포인트를 노출해야 합니다(--remote-debugging-port및 기본이 아닌--user-data-dir로 시작된 Chromium 또는 브라우저 도구가 이미 사용하는 엔드포인트). 없으면 그 사실을 알리십시오. 브라우저를 시작하거나 값을 붙여넣지 마십시오.- 브라우저 도구로 페이지로 이동한 다음 페이지의 정확한 URL과 대상 입력만 일치하는 CSS 선택기를 전달하십시오. URL에 변동 가능한 쿼리 매개변수가 있는 경우
--page-match origin-path를 추가하고, 필드로 가는 길에 각 iframe에 대해--frame-selector를 추가하고, 동일한 URL이 여러 컨텍스트에서 열려 있는 경우--context-index를 추가하십시오. - 해당 탭에서 DevTools를 닫고 채우는 동안 추적, 스크린캐스트, HAR 및 비디오 녹화를 끄십시오. agentenv는 감지할 수 없는 다른 레코더는 무시하고 열린 DevTools 창에서만 실패합니다.
- 명령을 실행하십시오. 성공 시
{"version":1,"backend":"cdp","effect":"field-filled"}만 출력됩니다. 필드의 이전 내용이 대체되었으며 페이지가 일반 입력 이벤트를 수신했습니다. 자체 도구로 계속 제출하십시오.
environment 사용을 허용하는 자격 증명만 채울 수 있습니다. 값은 제어 문자, 줄 구분 기호 또는 양방향 제어 문자가 없는 최대 8,192바이트의 단일 행이어야 합니다(그렇지 않으면 value-unsupported). 명령 제공자는 터미널 없이 실행되며 후행 개행 문자 하나가 제거됩니다. 비어 있거나, NUL이거나, UTF-8이 아닌 제공자 출력은 자격 증명 오류입니다(종료 코드 4). 전체 작업(첫 번째 액세스 시 키체인 권한 부여 대화 상자 포함)은 --timeout-ms(기본값 30,000) 아래에서 실행됩니다. 사용자가 해당 대화 상자를 클릭해야 하는 경우 시간을 늘리십시오. credential fill은 필드를 확인하거나, 양식을 제출하거나, 로그인하지 않습니다. 효과를 보고하고 관찰하지 않은 성공을 보고하지 마십시오.
stderr의 실패 이유(credential-fill: <reason>: <message>). 종료 코드 8, 변경 사항 없음: backend-unavailable, permission, connect-failed, version-unsupported, recording-conflict, context-absent, page-absent, page-ambiguous, frame-absent, frame-ambiguous, frame-invalid, target-absent, target-ambiguous, target-hidden, target-disabled, target-readonly, target-unfillable, target-changed, value-unsupported, timeout, cancelled. 종료 코드 11, 필드에 값이 있을 수 있음: timeout, cancelled, 또는 값이 전송된 후 delivery-failed, 전달된 값 후 cleanup-unconfirmed.
특권 실행
요청이 구성된 sudo-target을 사용하는 경우, 해당 대상을 계획, 확인, 실행, 생성 또는 순환하기 전에 references/sudo-execution.md를 읽으십시오.