Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Agent eval과 백엔드

Agent eval은 지정한 백엔드 하나와 모델 하나로 Artifact를 리뷰합니다. 모델은 선언한 읽기 전용 도구로 Artifact를 살펴보고, 엄격한 형식의 GREEN 또는 RED 판정을 돌려줍니다.

Agent 리뷰

artifactize는 모델 목록을 따로 제공하지 않으며, 여러 위치에서 자격 증명을 찾거나 지정한 모델을 다른 모델로 대체하지도 않습니다.

# Inside [evals.review]
profile = { kind = "agent", backend = "openai", model = "YOUR_EXACT_MODEL_ID", reasoning = "high", timeout_ms = 240000 }

backend에는 기본 provider(openai, anthropic, gemini, codex, claude-agent)나, eval을 실행하는 머신에 등록한 커스텀 provider의 이름을 씁니다. openai, anthropic, gemini는 OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY에 든 키를 쓰고, 없으면 artifactize login openai|anthropic|gemini나 데스크톱 앱의 Settings에서 저장한 키를 씁니다. 그 밖의 자격 증명은 찾지 않습니다. 키는 공백 없는 출력 가능한 ASCII 문자 1–4096개이며, 앞뒤 공백은 지웁니다. 변수가 설정되어 있으면 그 키를 씁니다. 값이 잘못되었으면 저장한 키로 넘어가지 않고 오류가 납니다. 유효한 유니코드가 아닌 값은 설정되지 않은 것으로 보아 저장한 키를 씁니다. codex는 ChatGPT 로그인을, claude-agent는 내 Claude Code와 그 로그인을 씁니다(Codex, Claude Agent 참고). provider와 effort는 설정에서 쓸 수 있는 별칭이 아닙니다. 0.5.0에서 chatgpt(Sign in with ChatGPT)와 claude(Claude CLI) 백엔드가 없어졌으며, 아직 이를 선언한 프로필이 있으면 config check가 대신 쓸 백엔드를 알려 줍니다.

artifactize models openai            # model ID and display name, in provider order
artifactize models anthropic --json
artifactize models gemini
artifactize models codex
artifactize models claude-agent

모델 목록 조회에는 별도의 고정 제한 시간이 있습니다. API 키를 쓰는 백엔드와 커스텀 provider의 목록 조회, Codex 모델 요청은 30초, Claude Agent 초기화는 25초까지입니다. 시간이 초과되면 목록을 가져오지 못합니다(API 목록 조회에서는 Model listing timed out.). eval의 timeout_ms를 늘려도 이 제한 시간은 늘어나지 않습니다. 연결 상태를 확인하고, claude-agent라면 Claude Code가 정상적으로 시작되는지도 확인한 뒤 다시 시도하세요.

reasoning은 선택 항목입니다. OpenAI와 Codex는 none, minimal, low, medium, high, xhigh, max를, Anthropic은 low, medium, high, max를, Claude Agent는 low, medium, high, xhigh, max를, Gemini는 minimal, low, medium, high를 받습니다. 그 밖의 값은 선언 오류이며, 다른 값으로 바꿔서 보내지 않습니다. 커스텀 provider에서는 해당 API가 지원하는 값을 쓸 수 있으며, 지원 여부는 리뷰를 시작할 때 확인합니다. 요청한 설정을 모델이 지원하지 않으면 provider에서 오류가 납니다. artifactize가 다른 모델로 바꾸거나 강도를 낮추지는 않습니다. 응답에 모델 ID가 나오면 정확히 일치해야 합니다.

Agent eval도 Runtime eval처럼 입력 eval이 끝날 때까지 실행을 미루고, 결과를 재사용하며, 리뷰가 끝난 뒤 입력을 다시 확인합니다. 백엔드, 모델, reasoning, 제한은 실행 옵션일 뿐 재사용 키에 들어가지 않습니다. eval, Artifact 종류, fingerprint가 같으면 모델이나 프로필이 달라도 결과를 재사용하며, 결과를 만들 때 쓴 모델과 프로필은 기록에 표시됩니다.

payload.instruction에는 무엇을 확인하고 무엇을 GREEN으로 볼지 쓰세요. 대상이 지켜야 할 기준을 적으면, 리뷰어가 그 기준에 비추어 GREEN 또는 RED와 지적 사항을 돌려줍니다. 리뷰어는 리뷰만 합니다. 구현이나 수정은 하지 않고, 선언된 Artifact 도구만 실행합니다. 테스트를 실행하거나 테스트 대상 코드를 불러오지 않고, 테스트 코드를 읽어 평가 기준에서 요구하는 사항을 충분히 검증하는지 판단합니다. 테스트 모음이 통과하는지 확인하려면 그것을 실행하는 Runtime eval을 선언하세요. 다른 Artifact는 {name}으로 참조하세요. 리뷰어는 대상과 참조된 Artifact, 그것을 읽는 도구를 이미 알고 있으므로 지시문에 도구 이름을 적을 필요는 없습니다.

Agent 리뷰는 스키마로 검사한 GREEN 또는 RED 판정을 돌려줍니다. 모델이 잘못된 결과를 돌려주면 artifactize가 한 번 고쳐 달라고 요청하고, 그래도 잘못되면 리뷰는 ERROR가 됩니다. Agent 응답에서 결과, 검사, 수정 요청 턴을 설명합니다.

재시도, 도구 결과, 사용량 수치는 Agent 백엔드에 있습니다.

Agent 프로필 제한

Agent 프로필에서 max_tokens와 max_tool_calls로 리뷰의 한도를 정할 수 있습니다.

profile = { kind = "agent", backend = "codex", model = "YOUR_EXACT_MODEL_ID", max_tokens = 100000, max_tool_calls = 100 }

모델 서비스는 입력과 출력 텍스트의 양을 토큰 단위로 셉니다. 토큰은 단어보다 작은 텍스트 조각일 수 있습니다. 로그인이나 리뷰 저장소의 토큰과는 상관없습니다. 두 예산 모두 선택 항목이며 1부터 9007199254740991까지의 정수를 받습니다. 생략하면 그 예산은 무제한입니다. 이는 provider의 생성 매개변수가 아니라 클라이언트 쪽 리뷰 예산입니다. max_tokens로 제한하는 사용량은 모든 턴, 수정 요청 턴, 다시 보낸 턴의 모든 시도에서 응답에 보고된 total_tokens를 합산한 값입니다(보고된 캐시 읽기·쓰기 포함). 합계가 보고되지 않으면 0으로 셉니다. 사용량은 응답을 받은 뒤에 확인하고 합계가 한도를 넘을 때만 실패로 처리하므로, 실제 사용량은 한도를 넘을 수 있으며 이 설정이 생성량이나 비용의 엄격한 상한이 되지는 않습니다.

max_tool_calls는 도구를 실행하기 전에 호출 시도를 세며, 성공한 호출뿐 아니라 모르는 도구, 잘못된 호출, 실패한 호출도 포함합니다. 둘 중 하나라도 넘으면 PROVIDER_BUDGET_EXCEEDED로 작업을 멈춥니다. 수정 요청과 재시도에도 원래 리뷰의 제한 시간과 예산을 적용하며, 예산을 추가하지 않습니다.

Agent 도구

리뷰어에게 필요한 읽기 전용 도구를 선언하세요. 내장 도구, 사용자 정의 명령, 호출 사이에 테스트 하네스를 계속 실행해 두는 세션은 도구에서 설명합니다. 아래의 저장된 Agent 대화는 도구 세션과 별개입니다.

Agent 백엔드

Agent 프로필, 백엔드, reasoning은 위의 Agent 리뷰에 있습니다. models 출력의 JSON 형태는 로컬 진단과 유지보수에 있습니다.

Agent 리뷰에서는 모델이 답변을 생성하는 동안 그 내용을 스트리밍으로 받습니다. 리뷰 전체의 제한 시간은 기본 240초이며, 모든 턴, 재시도, 도구 실행에 걸린 시간을 합쳐 셉니다. Anthropic 응답은 리뷰의 max_tokens와 별개로 턴마다 출력 토큰 16384개로도 제한됩니다.

재시도와 오류 코드

출력이나 토큰 사용이 생기기 전에 사용량 제한이나 일시적인 오류로 턴이 실패하면, provider가 안내한 만큼 기다렸다가 몇 차례 재시도합니다. claude-agent 리뷰는 Claude Code가 요청을 직접 재시도하므로 다시 보내지 않습니다(Claude Agent). 답변이 나오기 시작한 뒤에 실패한 턴(DEGENERATE_OUTPUT, 출력이 끝나지 않은 PROVIDER_ERROR, TRANSIENT)도 같은 횟수까지 재시도하며, 그 토큰은 max_tokens에 포함됩니다. 출력이나 사용량이 생긴 뒤의 다른 실패는 재시도하지 않습니다. 재시도로도 해결되지 않거나 provider가 요구한 대기 시간이 리뷰의 남은 시간보다 길면, 리뷰는 마지막 시도의 코드와 함께 ERROR로 끝납니다. 잠시 뒤 verify를 다시 실행하세요(완료된 결과는 재사용됩니다). 같은 식으로 계속 끝나면 다른 모델이나 reasoning을 써 보세요. 시도마다 수치, error, errorCode가 usage에 저장됩니다.

프롬프트 캐싱

provider는 매 턴 반복되는 대화 부분을 캐시하므로, 리뷰 후반에는 턴당 비용이 줄어듭니다. 얼마나 캐시되었는지는 usage에 있는 시도별 cacheReadTokens 수치로 확인하세요(verify --wait --json, run show, request show, session show --summary). 강제로 실행한 리뷰도 포함해 리뷰는 매번 새로 시작합니다. follow-up은 그 리뷰의 대화를 이어 가므로 캐시를 쓸 수 있습니다. 캐시 적중 여부는 provider가 정합니다. anthropic follow-up은 답이 판정이 아닌 일반 텍스트라서 대개 캐시가 적중하지 않습니다.

실패한 Agent 리뷰는 다음 errorCode 중 하나를 기록합니다.

errorCode원인재시도
AUTHENTICATION자격 증명이 없거나 만료됐거나 거부된 경우입니다. HTTP 401/403, API 키나 Codex 로그인이 없는 경우, 만료된 인증 파일, PATH에 claude가 없거나 Claude Code가 로그아웃된 경우가 여기에 해당합니다하지 않습니다. 백엔드를 멈춥니다
QUOTA결제, 크레딧, 요금제 사용량 한도(insufficient_quota, Codex 사용량 한도, Claude 구독 사용량 한도)하지 않습니다. 백엔드를 멈춥니다
RATE_LIMIT할당량 문제가 아닌 HTTP 429입니다. 재시도 뒤에도 실패했거나, Retry-After에 따른 대기 시간이 리뷰의 남은 시간 이상인 경우입니다합니다
TRANSIENT연결 실패, HTTP 5xx나 과부하, 끊긴 스트림입니다. 요청한 재시도 대기가 너무 길어도 이 분류를 유지합니다합니다. 출력 뒤에는 그 턴을 다시 보냅니다
TIMEOUT리뷰의 timeout_ms 제한 시간하지 않습니다
CANCELLEDRun을 직접 취소했습니다(run cancel 또는 MCP verify_cancel)하지 않습니다
PROVIDER_BUDGET_EXCEEDEDmax_tokens나 max_tool_calls를 넘었습니다하지 않습니다
INVALID_RESULT형식 수정을 한 번 요청한 뒤에도 유효한 판정이 없습니다하지 않습니다
DEGENERATE_OUTPUT모델 답변이 긴 공백으로만 계속되어 리뷰가 중단됐습니다합니다. 그 턴을 다시 보냅니다
PROVIDER_ERROR그 밖의 provider 실패: 거부된 요청, 알 수 없거나 요청과 다른 모델, 끝나지 않은 응답, 잘못된 도구 호출출력 한도에서 끊긴 답변(Length)만 그 턴을 다시 보냅니다
AGENT_ERROR그 밖의 모든 경우입니다. 예를 들어 잘못된 테스트 엔드포인트나 쓸 수 없는 도구가 해당합니다하지 않습니다
BACKEND_STOPPED시작하지 않습니다. 그 Run에서는 그 백엔드로 새 리뷰를 보내지 않습니다—

provider 오류 메시지에 artifactize가 보낸 자격 증명의 일부가 포함되어 있으면, 표시하거나 저장할 때 그 메시지를 [withheld: it contained part of the credential sent]로 대체합니다. 추가 결과 필드와 명령 출력은 이렇게 가리지 않습니다.

Ctrl-C로 verify --wait를 중단해도 진행 상황 표시만 멈추며, Agent 리뷰와 Run은 계속 실행됩니다. 직접 취소를 요청해야 Run의 작업이 멈춥니다.

백엔드 멈추기

AUTHENTICATION이나 QUOTA 실패는 같은 백엔드의 모든 리뷰에서 똑같이 반복되므로, 그 Run에서는 그 백엔드로 새 리뷰를 보내지 않습니다. 이후 그 Run에서 같은 백엔드로 실행하려던 리뷰는 시작하지 않고 BACKEND_STOPPED인 ERROR가 되며, 오류 메시지에 원래 실패가 나옵니다. 그 백엔드에 실행 자리가 없어 대기 중이던 요청(백엔드 수용량)도 대기열에서 빠져 같은 방식으로 BACKEND_STOPPED인 ERROR가 되며, 멈춘 백엔드는 자리를 차지하지 않습니다. 이미 실행 중이던 리뷰는 끝까지 실행되고, 재사용할 수 있는 결과는 계속 재사용하며, 다른 백엔드는 그대로 진행합니다. Run은 멈춘 백엔드를 stoppedBackends(verify --wait --json과 run show)에 남기고, verify는 이렇게 출력합니다.

Stopped backend openai after AUTHENTICATION in docs/review: 2 reviews not started.

다음 Run에서는 그 백엔드를 다시 쓸 수 있습니다.

eval의 범위에 있는 도구만 제공하며, 도구는 하나씩 차례로 실행됩니다. 각 도구가 무엇을 받고 돌려주는지는 Agent 도구에 있습니다. PNG/JPEG/WebP 결과는 모든 백엔드에 보내며, 이미지를 지원하지 않는 모델은 provider의 오류로 실패합니다. 요청의 시도별 usage는 성공했을 때와 ERROR일 때 모두 저장합니다. 캐시가 적중하면 해당 시도의 사용량을 reusedUsage에 기록하고, 이번 실행에서 발생한 사용량에는 포함하지 않습니다. 수치는 provider가 보고한 값(0으로 보고한 경우 포함)이며, 추정한 합계나 비용이 아닙니다. Anthropic의 inputTokens는 캐시하지 않은 입력만 센 값이고 캐시 읽기·쓰기 수치는 따로 있습니다. OpenAI의 입력에는 캐시 읽기가 이미 포함되어 있습니다. 모든 수치를 더하지 마세요. 보고되지 않은 필드는 빠집니다. 요청에는 판정, 결과, 사용량이 남고, 메시지, reasoning, 도구 호출과 그 인자, 결과는 리뷰의 저장된 대화에만 있습니다. session show --summary가 이를 집계합니다.

백엔드를 본격적으로 쓰기 전에, 계정에서 쓸 수 있는 정확한 모델 ID와 선언한 도구 하나로 간단한 시험용 리뷰를 한 번 실행하고 run show로 결과를 확인하세요. 모델 없이 도구와 스키마를 시험하려면 가짜 provider를 쓰세요.

저장된 대화

artifactize는 Agent 리뷰 대화를 이 머신에 저장합니다. 그래서 저장된 대화에서 리뷰어가 무엇을 보고 어떤 답변을 했는지 확인하고, 채팅하듯 follow-up을 보낼 수 있습니다. 기록된 판정은 절대 바뀌지 않습니다.

저장되는 내용. 리뷰 세션은 내 계정만 읽을 수 있는 곳에 저장합니다 (저장소). 지시문, 모든 메시지, 도구 호출과 그 결과, 수정 요청 턴, 토큰 수, 리뷰에 쓴 설정이 들어 있습니다. 저장에 실패해도 리뷰는 실패하지 않습니다. 쓰기 오류는 stderr에 출력하고 리뷰는 저장 없이 계속됩니다.

참조. 대화가 저장된 요청을 verify --wait --json, run show, request show로 확인하면 session 필드가 나옵니다.

"session": {
  "producer": "alice@laptop",
  "state": "34bb3c3a-9480-4a54-9ab3-3bce54e043b8",
  "runId": "run-FiVNCV",
  "requestId": "run-FiVNCV-1",
  "sessionId": "e83bf374-5136-484c-8d2f-2ce38ee4ca57",
  "ref": "alice@laptop/34bb3c3a-9480-4a54-9ab3-3bce54e043b8/run-FiVNCV/run-FiVNCV-1/e83bf374-5136-484c-8d2f-2ce38ee4ca57"
}

producer는 리뷰를 실행한 user@host이고, state는 그 상태 데이터베이스의 고정 ID입니다. 결과를 재사용한 요청은 그 결과를 만든 리뷰를 가리킵니다. 팀 리뷰 저장소는 Agent 결과마다 대화가 아니라 이 참조만(producer.session으로) 함께 보내므로, 팀원의 판정을 보면 그 대화가 어느 팀원의 상태 디렉터리에 저장되어 있는지 알 수 있습니다.

저장된 대화는 session show로 읽고, session show --summary로 집계하고, session send로 follow-up을 보냅니다. Agent 세션을 보세요.

Codex

codex 백엔드는 사용 중인 ChatGPT 요금제에서 이용할 수 있는 Codex 모델(gpt-6-luna, gpt-6.1-sol 등)로 리뷰합니다.

artifactize login codex     # sign in to ChatGPT in the browser
artifactize models codex    # the account's Codex models
# Declare backend = "codex", model = "gpt-6-luna", reasoning = "max", then:
artifactize verify --all --wait
artifactize logout codex    # delete artifactize's tokens; their revocation is attempted
  • 로그인. login codex는 Codex CLI처럼 브라우저에서 ChatGPT 로그인 페이지를 열고, 로그인하면 artifactize로 돌아옵니다. 브라우저 단계, 주소를 붙여 넣는 대체 방법, 5분 제한은 로그인 설정에 있습니다. 토큰과 ChatGPT 계정 ID는 나만 읽을 수 있는 $STATE/auth/codex.json에 저장합니다. login, models, verify에는 같은 --state-dir을 쓰세요. 토큰은 절대 저장소 안에 저장하지 않습니다. $STATE/auth가 git 워크트리, artifactize 작업 공간, --repo 안에 있으면 login codex는 그 폴더 경로를 알려 주며 로그인을 거부하고 doctor는 경고합니다(상태). 저장소 바깥의 상태 디렉터리나 ARTIFACTIZE_CODEX_AUTH_FILE을 쓰세요. artifactize는 액세스 토큰이 만료되기 전에 갱신합니다. 서버가 갱신 토큰을 더 이상 허용하지 않으면 artifactize는 저장된 토큰을 지우고, 리뷰는 다시 로그인하라는 오류로 끝납니다.

  • 기존 Codex 로그인 사용하기. 예를 들어 ARTIFACTIZE_CODEX_AUTH_FILE을 ~/.codex/auth.json으로 설정하면, artifactize에 저장된 토큰 대신 매 턴 그 파일의 tokens.access_token(과 tokens.account_id)을 읽습니다. 지정한 파일은 1 MiB 이하의 일반 파일이어야 하며, 그렇지 않으면 거부되어 로그인 정보로 쓰이지 않습니다. 그 파일을 쓰거나 복사하거나 갱신하지는 않습니다. 토큰 만료까지 남은 시간이 1분 이하이면 리뷰는 codex login 등으로 Codex에 다시 로그인하라는 메시지와 함께 실패합니다. logout codex는 그 파일을 건드리지 않습니다.

  • 요청. provider는 대화를 보관하지 않습니다. 선언한 reasoning은 max를 포함해 그대로 보내며, reasoning 요약은 Monitor에 나옵니다. 재시도, 예산, 도구 결과, 프롬프트 캐싱, 사용량은 openai와 같습니다.

  • 오류. 사용량 한도는 QUOTA이며, 요금제와 초기화 시각을 알려 주고 그 Run에서 codex를 멈춥니다. 단순한 HTTP 429는 RATE_LIMIT이며 재시도합니다. HTTP 401과 403은 AUTHENTICATION이며 다시 로그인하는 방법을 알려 줍니다. 토큰을 갱신할 때 토큰 엔드포인트에 연결하지 못하거나 오류 응답을 받으면 TRANSIENT로 분류합니다.

  • 모델. models codex는 지금 계정으로 Codex 모델 선택기에서 고를 수 있는 모델을 서버가 보내 준 순서대로 나열합니다. 프로필에는 목록에 표시되지 않더라도 계정에서 사용할 수 있는 모델을 지정할 수 있습니다.

Claude Agent

claude-agent 백엔드는 사용자의 Claude Code를 통해 리뷰하며, Claude Code에 로그인한 계정을 그대로 사용합니다. Claude Pro·Max 구독이나 API 키, 클라우드 계정으로 로그인한 Claude Code를 사용할 수 있습니다.

artifactize login claude-agent      # runs Claude Code's own claude auth login
artifactize models claude-agent     # the models Claude Code offers
# Declare backend = "claude-agent", model = "claude-opus-5-5", reasoning = "high", then:
artifactize verify --all --wait
  • 로그인. 로그인 정보는 Claude Code가 직접 보관합니다. login claude-agent와 데스크톱 앱의 Settings → Providers → Claude Agent는 Claude Code 자체 명령인 claude auth login을 실행합니다. Claude Code가 브라우저를 열고, 열리지 않았을 때 열 URL을 출력하며, 페이지에 나온 코드는 터미널이나 데스크톱 앱의 코드 입력란에 붙여 넣을 수 있습니다. 로그인은 Claude Code가 종료되면 끝나며(로그인 성공 또는 Claude Code의 오류), 10분이 지나면 멈춥니다. logout claude-agent는 claude auth logout을 실행합니다. 데스크톱 앱은 claude auth status가 알려 주는 대로 로그인 방식과 요금제를 보여 주며, 계정 정보는 보여 주지 않습니다. artifactize는 로그인 정보를 읽거나 복사하거나 저장하지 않으며, Claude Code와 서비스 사이에 끼어들지도 않습니다. 직접 claude auth login으로 로그인해도 똑같이 쓸 수 있습니다. PATH에 2.1.248 이상의 claude가 있어야 하며, 그보다 오래된 버전이면 claude update를 실행하라는 메시지와 함께 거부합니다. doctor는 claude를 실행하지 않고 위치만 보여 줍니다.
  • 리뷰. 리뷰어는 eval에 선언한 Artifact 도구만 쓸 수 있으며, max_tool_calls, max_tokens, 마감 시간도 다른 백엔드와 같습니다. 그 밖의 Claude Code 설정은 리뷰에 쓰이지 않습니다. Claude Code 자체 도구, Claude Code 설정, 훅, CLAUDE.md, 메모리, 스킬, MCP 서버는 모두 빠지고, 리뷰 내용이 내 Claude Code 세션 목록에 남지도 않습니다. 선언한 모델과 reasoning을 그대로 쓰며, Monitor에는 모델의 thinking 요약과 답변이 나오는 대로 표시됩니다. 판정과 형식 수정 요청 한 번은 다른 백엔드와 같습니다.
  • 오류. Claude Code가 실패한 요청을 직접 재시도하므로 artifactize는 다시 보내지 않습니다. 구독 사용량 한도에 걸리면 QUOTA이며, 어느 구간(5시간 또는 주간)인지와 초기화 시각을 알려 주고 그 Run에서 claude-agent를 멈춥니다. Claude Code가 로그아웃된 상태면 AUTHENTICATION이며 claude auth login을 실행하라고 알려 줍니다. 결제 문제는 QUOTA입니다.
  • 사용량. 응답 하나가 usage의 시도 하나이며, Claude Code가 알려 준 토큰 수를 기록합니다. 구독에서는 비용이 나오지 않습니다.
  • 모델. models claude-agent는 모델을 호출하지 않고, Claude Code가 지금 로그인으로 제공하는 모델을 model에 쓰는 모델 ID로 나열합니다. 프로필에는 목록에 없더라도 Claude Code가 받는 모델을 지정할 수 있습니다.
  • follow-up. 다른 백엔드와 마찬가지로 session send로 follow-up을 보낼 수 있습니다. 리뷰어는 리뷰 대화를 바탕으로 일반 텍스트로 답하며, 필요하면 Artifact를 다시 읽습니다. 기록된 판정은 바뀌지 않습니다.

커스텀 provider

프로젝트에는 provider 이름만 적습니다. 그 이름이 어디로 연결되는지는 eval을 실행하는 머신마다 따로 설정합니다. 커스텀 provider는 Agent 프로필의 backend에 쓸 수 있는 이름으로, 데스크톱 앱의 Settings → Providers에서 + Custom provider를 누르거나 artifactize provider로 추가합니다. 종류는 둘 중 하나입니다.

  • 별칭(alias): 기본 provider를 다른 이름으로 쓰며, 그 provider의 로그인이나 키를 그대로 씁니다.

    artifactize provider add work --alias codex
    
  • 엔드포인트: API, 루트 URL, 키(선택)를 지정합니다. API는 openai-responses, openai-chat(호환 서버 대부분이 지원하는 Chat Completions), anthropic, gemini 중 하나입니다. --key를 주면 키를 명령줄이 아닌 stdin에서 읽습니다.

    artifactize provider add local --api openai-chat --url http://localhost:11434/v1
    printf '%s\n' "$ROUTER_KEY" | artifactize provider add router --api openai-chat --url https://openrouter.ai/api/v1 --key
    

URL은 요청을 보낼 API 루트로, 기본 provider의 루트(https://api.openai.com/v1, https://api.anthropic.com, https://generativelanguage.googleapis.com)와 같은 형태입니다. http://나 https://로 시작하고 호스트가 있어야 하며, 자격 증명(user:pass@), 쿼리(?…), 프래그먼트(#…)가 든 URL은 거부합니다. 키는 따로 입력하기 때문입니다. 끝의 /는 지웁니다. 이미 있는 이름으로 provider add를 실행하면 그 provider를 바꾸고, provider remove NAME은 삭제합니다. provider list는 커스텀 provider 전체와 기본 provider의 키를 어디서 가져오는지 보여 주며, 키 값은 보여 주지 않습니다. 기본 provider의 이름은 커스텀 provider 이름으로 쓸 수 없습니다.

profile = { kind = "agent", backend = "local", model = "YOUR_EXACT_MODEL_ID" }

이 머신에 등록되지 않은 provider를 지정한 리뷰는 AUTHENTICATION ERROR로 끝나며, 오류 메시지에 그 provider 이름이 표시됩니다. 키와 커스텀 provider는 본인만 읽을 수 있는 $STATE/auth/providers.json에 저장되고, 저장소 안에는 저장되지 않습니다. 이 파일은 최대 1 MiB까지만 읽습니다. 이를 넘으면 provider를 읽거나 바꾸는 명령이 모두 Credential file is too large. 오류로 실패하며, logout과 provider remove도 마찬가지라 이 명령으로는 파일을 줄일 수 없습니다. 대신 providers.json을 $STATE/auth/ 밖으로 옮겨 백업으로 두고, 계속 쓸 키와 provider를 login과 provider add로 다시 저장하세요. provider도 모델, reasoning과 마찬가지로 실행 옵션이라 결과마다 기록되지만 재사용 키에는 들어가지 않습니다.

가짜 provider로 테스트하기

모델 없이 도구, 스키마, 결과 해석을 시험하려면 백엔드를 이 머신의 가짜 provider에 연결하세요. 아래 변수로 provider의 API 루트를 바꿀 수 있습니다.

백엔드변수예가짜 provider가 응답할 요청
openaiARTIFACTIZE_OPENAI_BASE_URLhttp://127.0.0.1:8080/v1POST <root>/responses, GET <root>/models
anthropicARTIFACTIZE_ANTHROPIC_BASE_URLhttp://127.0.0.1:8080POST <root>/v1/messages, GET <root>/v1/models
geminiARTIFACTIZE_GEMINI_BASE_URLhttp://127.0.0.1:8080POST <root>/v1beta/models/<model>:streamGenerateContent, GET <root>/v1beta/models
codexARTIFACTIZE_CODEX_BASE_URLhttp://127.0.0.1:8080/backend-api/codexPOST <root>/responses, GET <root>/models
Codex 로그인ARTIFACTIZE_CODEX_AUTH_URLhttp://127.0.0.1:8080POST <root>/oauth/token과 <root>/oauth/revoke입니다. login codex는 브라우저를 <root>/oauth/authorize로 보냅니다
  • 루트는 localhost, 127.0.0.0/8, [::1]의 http://나 https://여야 하며, 자격 증명, 쿼리, 프래그먼트가 없어야 합니다. 그 밖의 값이면 연결하기 전에 리뷰, models, doctor가 그 변수 이름을 알려 주며 실패합니다. 빈 값은 설정하지 않은 것으로 간주합니다. anthropic은 끝에 /v1이 붙어도 됩니다.
  • 이때도 키(변수나 저장한 키)가 필요하고 가짜 provider에 그대로 전달되므로 아무 값이나 넣어 두세요. 커스텀 엔드포인트에는 변수가 필요 없으며, URL을 가짜 provider 주소로 지정하면 됩니다. codex는 ARTIFACTIZE_CODEX_AUTH_FILE을 {"tokens":{"access_token":"dummy","account_id":"test"}} 같은 파일로 지정하세요.
  • 그 밖에는 바뀌는 것이 없습니다. 요청 본문과 스트리밍, 재시도, 예산, 도구 호출, 수정 요청, 판정 검사가 모두 같습니다.
  • 결과는 다른 결과처럼 기록되고 재사용되므로 버려도 되는 상태 디렉터리(--state-dir나 ARTIFACTIZE_STATE_HOME)를 쓰세요. 테스트 엔드포인트가 설정되어 있으면 verify가 리뷰 저장소 사용을 거부하므로 ARTIFACTIZE_REMOTE=off로 설정하세요. 가짜 결과가 든 상태는 절대 remote push하지 마세요.
  • 테스트 엔드포인트가 설정되어 있는 동안 doctor는 경고하고 이를 testEndpoint로 알립니다.
  • claude-agent에는 테스트 엔드포인트가 없습니다. Claude Code가 서비스에 직접 연결하기 때문입니다.

가짜 provider는 요청에 지정된 모델의 응답을 해당 provider의 전송 형식에 맞춰 text/event-stream으로 스트리밍합니다. openai라면 response.completed 이벤트 하나면 됩니다. GREEN 스키마가 {"verdict":"GREEN"}만으로 충족되는 리뷰는 이 가짜 provider로 통과시킬 수 있습니다. pass_schema에 다른 필드가 필요하면 가짜 provider의 text 응답에 그 필드의 유효한 값을 넣으세요. 그러지 않으면 응답이 스키마에 맞지 않아 artifactize가 한 번 수정을 요청하고, 수정한 응답도 맞지 않으면 INVALID_RESULT가 됩니다.

#!/usr/bin/env python3
"""A fake OpenAI Responses provider on loopback that returns a verdict-only GREEN response."""
import json
from http.server import BaseHTTPRequestHandler, HTTPServer


class Fake(BaseHTTPRequestHandler):
    def do_POST(self):
        request = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
        text = json.dumps({"verdict": "GREEN"})
        response = {
            "id": "resp_fake", "object": "response", "created_at": 0,
            "model": request["model"], "status": "completed",
            "output": [{"type": "message", "id": "msg_fake", "role": "assistant",
                        "status": "completed",
                        "content": [{"type": "output_text", "text": text, "annotations": []}]}],
            "usage": {"input_tokens": 1, "output_tokens": 1, "total_tokens": 2},
        }
        event = {"type": "response.completed", "sequence_number": 0, "response": response}
        body = f"event: response.completed\ndata: {json.dumps(event)}\n\n".encode()
        self.send_response(200)
        self.send_header("Content-Type", "text/event-stream")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)


HTTPServer(("127.0.0.1", 8080), Fake).serve_forever()
python3 fake_openai.py &
export ARTIFACTIZE_OPENAI_BASE_URL=http://127.0.0.1:8080/v1 OPENAI_API_KEY=dummy
ARTIFACTIZE_REMOTE=off artifactize --state-dir "$(mktemp -d)" verify --all --wait

명령 도구를 모델 없이 따로 시험하려면 tools check --execute를 쓰세요. 입력과 출력은 명령 도구 프로토콜을 따릅니다.