비용 관리

AI Agent용: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/cost-management/index.md에 있습니다. 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.

Ankole이 지출하는 비용의 대부분은 model token이며, 그중 대부분은 사용자가 통제할 수 없는 사용량이 아니라 소수의 구성 레버(configuration lever)에 의해 결정됩니다. 이 페이지는 각 레버의 이름과 각각이 어떤 비용을 들이고 무엇을 절약하는지, 그리고 청구 금액이 너무 높을 때 잡아당겨야 할 순서를 설명합니다. 여기 나오는 모든 레버는 control plane의 실제 노브(knob)이며, “Agent를 덜 사용하라”는류의 조언은 없습니다.

중요한 속성을 먼저 밝히자면, 비용은 어떤 model이 몇 번, 얼마나 오래 실행되는지의 함수입니다. 레버는 이 세 가지에 대응합니다. model-profile 계층은 model을 선택하고, agent-loop 예산은 반복 횟수를 제한하며, job 재시도 및 슬롯 상한은 폭주하는 경우를 묶어 둡니다. 지출이 발생하는 지점에 맞는 레버를 당기세요.

레버 1: model-profile 계층

8개의 내장 Agent profile은 서로 다른 유료 경로를 제어합니다. 5개는 언어 모델을 선택하고, 3개는 웹 검색, 웹 가져오기, 이미지 생성 기능을 연결합니다.

Brain이 유지하는 인스턴스 공용 모델 설정은 embedding과 rerank뿐입니다. AppConfigure에서 활성 Brain 유지보수 Agent를 선택합니다. 모든 Brain 모델 호출은 이 Agent의 ID로 실행되고 사용량도 이 Agent에 귀속됩니다. 해당 Agent의 light profile은 대화와 Source의 지식 추출, heavy profile은 Dreaming과 Skill 교훈 재검토, web_fetch profile은 URL Source 가져오기에 사용합니다. web_fetch가 설정되지 않았거나 Provider 요청이 실패하면 로컬 ankole-browser를 사용합니다. 유지보수 Agent를 비활성화하면 다시 활성화하거나 교체할 때까지 모델 호출과 로컬 URL 가져오기가 모두 중지됩니다. Brain → 상태에서 선택한 Agent와 각 profile 상태를 확인할 수 있습니다. 전체 동작은 Brain을 참조하십시오.

가장 많이 절약하는 두 가지 조치:

• light를 저렴한 model에 바인딩하세요. 이 슬롯은 대량 처리 경로를 위해 존재합니다. primary와 비슷한 비용의 light는 슬롯의 의미를 무너뜨립니다.
• 기본적으로 primary를 낮추지 올리지는 마세요. “비싸게 느껴지는” agent는 실제로 수행하는 작업에 비해 너무 무겁게 바인딩된 primary인 경우가 많습니다. 품질이 요구할 때만 올리세요.

agent가 사용하지 않는 슬롯은 바인딩을 해제하세요. 그러면 vision_fallback에서 호출이 발생할 수 없습니다. 비어 있는 image_generate profile도 메인 provider가 해당 기능을 선언하면 네이티브 이미지 생성(native image generation)을 계속 사용할 수 있습니다. Background Agent Jobs는 다릅니다. profile이 설정되어 있지 않아도 Job은 AIGateway를 통해 Agent의 heavy profile을 폴백으로 사용하여 실행됩니다. Job에 다른 provider나 model이 필요할 때 이 profile을 구성하세요.

Workflow task는 전용 profile을 추가하지 않습니다. 생성 요청에서 사용 가능한 custom model profile을 선택하지 않으면 각 task는 Agent의 primary profile을 사용합니다.

레버 2: reasoning effort

Codex reasoning effort를 지원하는 provider에서 model_reasoning_effort는 7단계 다이얼입니다: minimal | low | medium | high | xhigh | max | ultra. 낮은 effort는 더 저렴하고 빠르며, 높은 effort는 어려운 문제에서 더 좋은 결과를 내고 비용이 더 듭니다. 기본값은 high입니다.

이것은 model을 바꾸는 것보다 더 세밀한 레버입니다. primary가 medium으로 충분한데 high로 설정된 agent는 눈에 보이는 이득 없이 더 많은 비용을 지출합니다. primary profile에서 agent의 실제 작업에 맞게 설정하고, 어려운 종합 작업을 하는 한 agent에게만 올리세요. 모든 agent에 올리면 안 됩니다.

레버 3: web 도구, 필요할 때만

web_search와 web_fetch는 독립적인 profile이며 호출할 때마다 비용이 듭니다. 두 가지 조치:

• agent가 web이 필요하지 않으면 바인딩을 해제하세요. 내부 전용 assistant는 web_search가 바인딩되어 있으면 안 됩니다. 슬롯이 존재한다는 것 자체가 호출 허가증이 됩니다.
• URL을 알고 있으면 web_search보다 web_fetch를 사용하세요. 알려진 소스를 fetching하는 것은 한 번의 호출입니다. 검색은 한 번의 호출에 더해 agent가 하기로 결정한 fetch가 추가됩니다.

worker.rendered_fetch_idle_ttl_ms AppConfigure 키는 렌더링된 fetch 결과가 캐시되는 시간을 제어합니다. TTL이 높을수록 같은 URL의 반복 fetch를 절약하지만 데이터가 오래될(staleness) 수 있습니다.

레버 4: agent-loop 예산

세 개의 AppConfigure 키가 turn당 지출을 제한합니다:

max_iterations는 수다스러운 agent loop를 제한하는 키입니다. 두 번이면 충분할 자리에 열 번 도구를 호출하는 loop는 model을 열 번 사용합니다. 상한을 낮추면 agent가 수렴하게 됩니다. max_output_tokens는 각 응답의 크기를 제한합니다. 이것들은 instance 전체의 기본값입니다. 일반적인 turn의 형태에 맞게 설정하고, 어려운 turn이 상한에 걸려 “가지고 있는 내용을 종합하라”는 최종 답변이 나올 수 있다는 점을 받아들이세요.

레버 5: background-job 재시도 및 슬롯 상한

Background job은 재시도에 token을 쓸 수 있으며, 그 상한이 레버입니다:

일시적으로 다섯 번 실패하는 job은 다섯 번 실행한 만큼의 token을 소비합니다. 대부분의 경우 상한이 보호해 줍니다. 구성 오류는 빠르게 실패하고 실패 상태로 유지됩니다. 주의할 레버는 세 번째입니다. 동시에 세 개의 job을 실행하는 agent는 한 번에 세 개의 model loop를 돌리는 것입니다. 그런 병렬성이 필요 없다면 persona(“한 번에 한 가지 일을 하라”)가 상한이 허용하는 것보다 더 저렴합니다.

레버 6: Workflow 호출 및 동시성 상한

Workflow의 agent() 호출은 각 attempt마다 완전한 model turn 하나를 실행합니다. 호출 하나는 재시도 가능한 실패가 지속되면 최대 3번의 attempt를 사용할 수 있습니다. 따라서 대충 나눈 많은 소형 task보다 의미 있는 작업 단위를 주고, 요청에서 max_agent_calls를 세울 수 있는 최소 상한으로 설정하세요.

Workflow 생성 요청의 concurrency와 max_agent_calls는 배포 상한을 높일 수 없고 더 낮은 값만 요청할 수 있습니다. Workflow v1은 전체 run을 위한 token 또는 금액 예산을 제공하지 않으며, 각 task는 일반 turn의 iteration, output-token, inactivity 상한을 그대로 적용받습니다. 자세한 사용 방법은 Workflows를 참조하세요.

레버 7: Agent별 token quota

위의 여섯 레버는 turn 하나의 비용을 결정합니다. token quota는 총량을 막습니다. Agent 하나가 반복 주기 동안 소비할 수 있는 token을 제한하며, 사용량이 한도에 도달하면 AIGateway는 주기가 끝날 때까지 그 Agent의 model 호출을 거부합니다.

Agent 페이지에서 설정합니다. 주기(일), 주기 시작 시각, token 한도를 입력합니다. Agent 페이지는 한도 대비 사용 비율과 현재 주기의 종료 시각을 보여 줍니다. 한도에 도달한 상태에서 도착한 chat 메시지는 사용한 token, 한도, 주기 종료 시각이 담긴 답장을 받습니다. 한도에 도달한 Background Agent Job은 기다리지 않고 실패합니다. 정당한 급증을 계속 진행해야 하면 주기 재설정으로 즉시 새 주기를 시작합니다.

quota는 예산 계획 도구가 아니라 정지 장치로 사용하세요. Agent가 한도에 가까워져도 속도를 늦추지 않으며, 호출 하나가 자신의 사용량만큼 한도를 넘겨 끝날 수 있습니다. 아래에서 관찰한 지출을 기준으로, 가장 무거운 정상 주간에 여유를 두고 크기를 정하세요. 필드는 Agents를 참조하세요.

지출이 실제로 발생하는 곳

model이나 동시성을 바꾸기 전에 Console을 사용하여 호출을 발생시킨 Agent, conversation 또는 Background Agent Job을 찾으세요:

• GET /ai-gateway/conversations는 최근 turn이 수행한 model 호출을 보여 줍니다. 어떤 profile이 해석되었는지, 몇 번 호출했는지, 어떤 provider인지. 이것은 지출이 primary(볼륨), heavy(몇 번의 비싼 호출) 또는 web_search(많은 소액 호출) 중 어디에 있는지 확인하는 가장 빠른 방법입니다.
• GET /background-agent-jobs는 job의 attempts를 보여 줍니다. attempts: 5인 job은 다섯 번 실행된 것입니다.
• 구조화된 control-plane 로그에는 provider 호출의 이벤트 이름과 필드가 포함됩니다. 로그 수집기(log ingester)에서 provider별, agent별로 집계할 수 있습니다.

해결 방법은 결코 “Agent를 덜 사용하라”가 아닙니다. “이 특정 agent의 작업에 대해 이 특정 레버가 잘못 설정되어 있다”가 해결 방법입니다.

실제 사례

deployment instance의 청구 금액이 일주일 만에 두 배가 되었습니다. conversations 화면에서 primary 호출은 정상이지만 web_search 호출은 10배로 늘었습니다. may_intervene가 설정된 팀 어시스턴트 agent가 모든 channel 메시지에서 검색을 시작한 것입니다. 해결 방법은 비용 레버가 아니라 persona(“누군가 사실 질문을 할 때만 검색하라”)입니다. 청구 금액은 판단 문제의 증상이었고, 판단이 사는 곳은 persona입니다.

이것이 패턴입니다. 비용 문제는 흔히 위장된 행동 문제이며, 행동 레버는 token 상한이 아니라 persona 또는 binding policy입니다.

비용 관리가 아닌 것

이것은 실시간 지출 대시보드가 아닙니다. Ankole은 그러한 대시보드를 제공하지 않습니다. 달러 금액으로 지출을 상한하는 방법도 아닙니다. 레버는 호출과 반복 횟수를 제한하며, 달러 금액은 provider의 요율에 그것들을 곱한 값입니다. 그리고 conversations 화면을 읽는 것의 대체재도 아닙니다. 어떤 레버가 잘못 설정되었는지 알아야만 레버를 당길 가치가 있습니다.

다음 단계

• Agent의 model profile에 대해서는 Agents 문서를 읽으세요.
• agent-loop 노브와 해당 키에 대해서는 Environment variables 문서를 읽으세요.
• 관련 conversation 및 Job 엔드포인트에 대해서는 Console API reference 문서를 읽으세요.
• Job 상한에 대해서는 Background Agent Jobs 문서를 읽으세요.
• Workflow 분할, 결과, 복구 규칙은 Workflows 문서를 읽으세요.