홈가이드
업데이트
AI 에이전트 컨텍스트 창: 100k 토큰 사용 방법
AI 에이전트 컨텍스트 창은 프롬프트, 도구 결과 및 모델의 답변이 공유하는 총 토큰 공간입니다. 이 API에서 해당 공간은 100,000 토큰이며, 장시간 실행되는 에이전트는 예상보다 빨리 이를 채웁니다.

주요 포인트
- 100,000 토큰 창은 프롬프트와 생성 결과를 포함하므로, 유지하는 도구 결과마다 다음 답변의 공간이 줄어듭니다.
- 에이전트 루프에서는 전체 기록이 매 단계마다 다시 전송되므로, 총 입력은 선형이 아닌 단계 수의 제곱에 따라 증가합니다.
- 먼저 오래된 도구 출력을 줄이고, 시스템 프롬프트와 최신 턴을 유지하며, 사용량 필드로 측정합니다.
- 단계당 1,500개의 새 토큰을 생성하는 20단계 루프의 총 비용은 약 $0.055입니다.
카드가 필요 없습니다. 가입 후 한 번의 클릭으로 $0.50의 무료 체험 크레딧을 청구하세요 (인당 한 번).
API 키 받기짧은 답변: 100,000 토큰의 공유 예산 하나
AI 에이전트 컨텍스트 창을 검색하는 사람들은 보통 에이전트가 깨지기 전에 얼마나 많은 것을 기억할 수 있는지 알고 싶어 합니다. 여기서 숫자는 100,000 토큰이며, 여기에는 시스템 프롬프트, 도구 정의, 이전 메시지 모두, 도구 결과, 그리고 모델이 작성할 생성 결과가 모두 포함됩니다. 생성 결과는 남은 공간을 사용할 수 있으며, max_tokens은 선택 사항입니다.
이로 인해 창은 저장 공간이 아닌 예산이 됩니다. 채팅봇은 제한에 거의 도달하지 않습니다. 도구 호출 루프에서 작동하는 에이전트는 각 단계가 모델 메시지 및 도구 결과를 기록에 추가하고 전체 기록이 다음 호출에서 다시 전송되므로 오후 한나절 만에 도달할 수 있습니다. 모델은 요청 간에 기억력이 없습니다. 기억처럼 보이는 것은 당신이 대화 기록을 다시 보내는 것입니다.
에이전트에서 창을 실제로 채우는 것
공간의 대부분은 사용자의 텍스트가 아닙니다. 이 다섯 가지 소스를 추적하면 실행이 어디에서 고갈되는지 예측할 수 있습니다.
- 시스템 프롬프트. 규칙, 페르소나 및 출력 형식. 종종 500~2,000 토큰이며 모든 호출에 전송됩니다.
- 도구 정의. 각 함수 이름, 설명 및 JSON 스키마가 계산됩니다. 긴 설명이 있는 10개의 도구는 첫 번째 사용자 메시지 전에 수천 개의 토큰이 소요될 수 있습니다.
- 도구 결과. 가장 흔한 원인입니다. 검색 결과, 파일 덤프 또는 데이터베이스 행 집합은 수천 개의 토큰이 될 수 있으며, 제거하지 않는 한 기록에 남아 있습니다.
- 어시스턴트 메시지. 텍스트로 작성된 추론 및 모델이 생성한
tool_calls인수. - 생성 중인 답변. 이에도 공간이 필요합니다. 프롬프트가 99,000 토큰인 경우 답변에는 약 1,000개가 남습니다.
API는 각 응답의 usage 블록에 정확한 숫자를 보고하므로 추측할 필요가 없습니다. 각 단계 후 prompt_tokens을 기록하면 곡선을 확인할 수 있습니다.
작동 예: 도구 루프의 20단계
3,000 토큰으로 시작하는 에이전트를 가정합니다 (시스템 프롬프트와 도구 정의 포함). 각 단계는 기록에 약 1,500 토큰을 추가합니다: 모델의 도구 호출과 도구의 결과입니다. 또한 각 단계당 약 300 토큰의 출력을 작성합니다. 에이전트는 20 단계를 실행합니다.
k 단계의 입력은 3,000 + 1,500 × (k − 1)입니다. 20단계에 걸쳐 합산:
- 3,000 × 20 = 고정 시작 부분에 대한 60,000 토큰, 매번 다시 전송됨.
- 1,500 × (0 + 1 + ... + 19) = 1,500 × 190 = 누적 기록의 285,000 토큰.
- 총 입력: 345,000 토큰. 총 출력: 20 × 300 = 6,000 토큰.
| 항목 | 토큰 | 1M당 가격 | 비용 |
|---|---|---|---|
| 입력 | 345,000 | $0.15 | $0.05175 |
| 출력 | 6,000 | $0.50 | $0.003 |
| 합계 | 약 $0.055 |
두 가지가 눈에 띕니다. 첫째, 20 단계의 컨텍스트는 3,000 + 1,500 × 19 = 31,500 토큰으로 창 내에 잘 들어갑니다. 그러나 기록이 매번 다시 전송되었으므로 345,000 입력 토큰에 대해 지불했습니다. 둘째, 완전히 가득 찬 창(100,000 입력 토큰)의 단일 호출은 입력 측면에서 100,000 × $0.15 / 1M = $0.015가 듭니다. 긴 컨텍스트는 호출당 저렴하지만, 비용은 여러 단계에 걸쳐 반복하면서 발생합니다. 가격 페이지에서 요금과 충전 보너스를 확인하세요.
창이 가득 차기 전에 몇 단계가 맞습니까
코드를 작성하기 전에 이를 추정할 수 있습니다. 답변을 위해 20,000 토큰 정도를 예비로 남겨 두면 프롬프트를 위해 80,000 토큰의 예산이 남습니다. 3,000 토큰의 시작과 단계당 1,500 토큰 추가를 고려하면, 기록은 (80,000 − 3,000) / 1,500, 즉 약 51 단계 후에 해당 예산에 도달합니다.
이제 이 길이의 실행 비용을 계산해 보겠습니다. 51 단계 동안 입력은 3,000 × 51 + 1,500 × (0 + 1 + ... + 50) = 153,000 + 1,500 × 1,275 = 153,000 + 1,912,500 = 2,065,500 토큰입니다. 단계당 300 토큰의 출력은 15,300 토큰입니다. 비용: 2,065,500 × $0.15 / 1M = $0.30983, 그리고 15,300 × $0.50 / 1M = $0.00765이므로 약 $0.32입니다.
약 $0.055의 20단계 실행과 비교합니다. 실행은 2.55배 더 길지만 각 단계가 더 긴 기록을 포함하므로 비용은 약 5.8배 더 듭니다. 이것이 기록을 줄이는 실용적인 이유입니다: 단계당 비용을 제한하고 창을 보호합니다.
에이전트를 창 안에 유지하기
먼저 오래된 도구 출력 삭제
원시 도구 결과는 오래된 기록에서 가장 크고 가장 비효율적인 부분입니다. 모델이 파일 목록을 처리한 후에는 목록을 다시 사용할 필요가 거의 없습니다. 오래된 결과를 "결과 삭제됨, 4,200 토큰"와 같은 한 줄 스텁으로 대체하거나 쌍을 완전히 삭제합니다.
중간 요약, 양쪽 끝 유지
시스템 프롬프트와 마지막 몇 턴을 그대로 유지하십시오. 그 사이의 모든 것에 대해 모델에게 결정 및 발견된 사실의 짧은 요약을 요청한 다음, 해당 요약을 단일 메시지로 저장하십시오. 제한에 도달한 후에가 아니라 도달하기 전에 요약 호출을 실행하십시오.
사실을 트랜스크립트에서 이동
에이전트가 몇 시간 동안 유지해야 하는 것을 배우면 도구를 통해 파일이나 작은 데이터베이스에 기록하고 필요할 때 다시 읽으십시오. 이는 모든 요청에 이를 운반하는 것보다 저렴하며 재시작 시에도 유지됩니다.
도구 스키마를 짧게 유지
모델이 도구를 선택하는 데 필요한 설명만 잘라내십시오. 작업의 현재 단계에 관련 있는 도구만 전달하십시오.
코드: 토큰 예산이 있는 도구 루프
이 루프는 대략적인 크기가 80,000 토큰의 예산을 초과할 때 가장 오래된 메시지를 잘라내어 답변을 위한 공간을 남깁니다. 이 추정은 문자를 4로 나누어 영어 텍스트에 대한 일반적인 근사치를 사용합니다. 실제 개수는 usage에서 반환됩니다. 잘라내기는 고아 tool 메시지를 제거하여 결과가 호출 없이 나타나지 않도록 합니다.
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://api.aivideogenapi.com/v1", api_key=os.environ["API_KEY"])
BUDGET = 80_000
tools = [{"type": "function", "function": {
"name": "get_scene_length",
"description": "Return the length of a scene in seconds",
"parameters": {"type": "object",
"properties": {"scene": {"type": "integer"}},
"required": ["scene"]}}}]
def rough_tokens(messages):
return sum(len(json.dumps(m)) for m in messages) // 4
def trim(messages):
system, rest = messages[0], messages[1:]
while rough_tokens([system] + rest) > BUDGET and len(rest) > 4:
rest.pop(0)
while rest and rest[0]["role"] == "tool":
rest.pop(0)
return [system] + rest
def run_tool(name, args):
return json.dumps({"seconds": 4 * args["scene"]}) # stub
messages = [
{"role": "system", "content": "You plan video scenes. Use tools for lengths."},
{"role": "user", "content": "Total the length of scenes 1 to 5."},
]
for step in range(20):
resp = client.chat.completions.create(
model="uncensored", messages=trim(messages), tools=tools)
msg = resp.choices[0].message
messages.append(msg.model_dump(exclude_none=True))
print(step, resp.usage.prompt_tokens)
if not msg.tool_calls:
print(msg.content)
break
for call in msg.tool_calls:
result = run_tool(call.function.name, json.loads(call.function.arguments))
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
도구 호출은 OpenAI 형식을 따릅니다: tools, tool_choice, 그리고 role: "tool"로 반환된 결과입니다. 문서에서 그대로 전달되는 매개변수 목록을 확인할 수 있습니다.
창 외에도 중요한 제한 사항
창은 하나의 제약 조건입니다. 에이전트는 속도 제한에도 부딪힙니다. 전체 키는 8개의 동시 요청과 분당 300개의 요청을 허용합니다. 체험 키는 2개와 60개를 허용합니다. 병렬 하위 에이전트가 있는 빠른 루프는 동시성 한계를 빠르게 초과할 수 있습니다. API는 HTTP 429와 오류 코드 concurrency 또는 rate_limited로 응답하며, 일시적 과부하 시 Retry-After: 5 헤더를 보냅니다. 그 시간만큼 기다렸다가 다시 시도합니다.
스트리밍하는 경우 스트리밍된 요청이 스트림이 끝날 때까지 동시성 슬롯을 보유한다는 점을 기억하십시오. 스트림을 닫지 않는 중단된 클라이언트는 슬롯을 계속 점유합니다.
최대 본문 크기는 8 MB로 텍스트 100,000 토큰보다 훨씬 크므로, 창이 먼저 도달할 제한입니다. 이 API를 기반으로 한 텍스트 전용 파이프라인의 예는 비디오 스크립트 가이드를 참조하세요. 실행할 준비가 되면 API 키를 생성하세요. 새 사용자는 한 번의 클릭으로 7일 동안 유효하고 결제가 필요 없는 $0.50의 체험 크레딧을 청구할 수 있습니다.
더 많은 가이드
질문과 답변
컨텍스트 창은 얼마나 큰가요?
프롬프트와 생성 결과를 합쳐 100,000 토큰입니다. 생성 결과는 프롬프트가 남긴 공간만큼 사용할 수 있습니다.
모델이 이전 요청을 기억합니까?
아니요. 각 요청은 독립적이므로, 모델이 확인해야 할 메시지를 코드에서 다시 전송해야 합니다.
제한을 초과하면 어떻게 됩니까?
요청이 제한을 초과하면 전송되지 않으므로, 전송 전에 대화 기록을 줄이거나 요약해야 합니다. 실패한 요청에는 요금이 부과되지 않습니다.
토큰은 어떻게 계산합니까?
각 응답의 usage 블록에서 prompt_tokens과 completion_tokens 값을 확인하거나, 전송 전 영어 기준 토큰당 약 4자로 대략 추정할 수 있습니다.
키는 양식 하나만 작성하면 받을 수 있습니다
계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.