KO ▾
API 키 받기

에이전트용 LLM 모델 API: 도구 호출 가이드

에이전트는 루프입니다: 모델이 도구를 선택하고, 코드가 이를 실행하며, 결과가 반환되면 모델이 다음 행동을 결정합니다. 여기 루프의 작동 예시와 계획에 필요한 제한 사항 및 비용이 있습니다.

업데이트

중앙 터미널 주변 도구 블록을 통과하는 오브의 등각 루프, 에이전트 워크플로우를 보여줌
01

주요 포인트

  • 엔드포인트는 도구, tool_choice, 스트리밍 tool_calls 및 role tool 결과를 지원합니다.
  • 루프에 한도를 설정하고, 도구 인수를 검증한 후 짧은 대기 후 429 응답을 재시도하세요.
  • 전체 키의 경우 병렬 워커를 8 이하로 유지하세요. 스트림은 종료될 때까지 슬롯을 차지합니다.
  • 문맥이 커지는 6단계 에이전트 실행에는 약 $0.005가 듭니다.

API가 에이전트에 제공해야 할 것

에이전트용 LLM 모델 API를 선택할 때 체크리스트는 마케팅이 시사하는 것보다 짧습니다. 신뢰할 수 있는 함수 호출, 실행 중인 대화 기록을 담을 수 있을 만큼 큰 컨텍스트 창, 예측 가능한 속도 제한, 많은 호출을 수행하는 루프에 불리하지 않은 가격이 필요합니다.

이 API는 표준 OpenAI 인터페이스를 통해 이러한 요구를 충족합니다. tools 및 tool_choice을 지원하며, 일반 및 스트리밍 응답 모두에서 tool_calls을 반환하고 role: "tool" 메시지 형태로 도구 결과를 받습니다. response_format을 통해 JSON 모드를 사용할 수 있습니다. 컨텍스트 창은 프롬프트와 출력 생성을 합쳐 100,000 토큰이며, 모델 ID는 uncensored입니다.

프레임워크 측이 OpenAI 클라이언트이므로, Base URL을 설정할 수 있는 대부분의 에이전트 라이브러리가 작동합니다. https://api.llmmodelsapi.com/v1을 가리키고 키를 제공한 후 모델을 지정하세요. 설정 방법은 문서에서 확인할 수 있으며, 키 페이지에서 키를 얻을 수 있습니다.

두 가지 제한 사항이 설계에 영향을 미칩니다. 첫째, 모델은 텍스트만 처리하므로 이미지, 오디오 또는 파일 처리는 도구에서 수행하여 텍스트로 반환해야 합니다. 둘째, 이 엔드포인트에는 임베딩이 없으므로 에이전트가 검색을 수행하는 경우 벡터 검색을 다른 소스에서 수행해야 합니다.

루프를 안정적으로 유지하는 시스템 프롬프트

대부분의 에이전트 실패는 모호한 지시에서 비롯되며 API 문제가 아닙니다. 좋은 시스템 프롬프트는 모델에게 자신의 정체성, 사용 가능한 도구, 중지 시점 및 최종 답변 형식을 알려줍니다. 다음은 연구 보조용 프롬프트입니다.

당신은 연구 보조원입니다. search_notes 및 read_note 도구를 호출할 수 있습니다. 이미 가지고 있지 않은 정보만 필요할 때만 도구를 호출하십시오. 도구 호출은 최대 5회까지 가능합니다. 충분한 정보를 얻었으면 짧은 답변과 함께 사용한 노트 ID 목록을 반환하십시오. 노트에 답변이 없으면 그 사실을 명확히 말하십시오.

이 프롬프트가 수행하는 작업을 주목하세요. 도구 이름을 명시하고, 호출 예산을 설정하며, 중지 조건을 정의하고, 모델이 모른다고 말할 수 있는 권한을 부여합니다. 이 마지막 부분이 중요한 이유는, 강제로 답변하게 만든 에이전트는 무언가를 만들어낼 것이기 때문입니다.

도구 사용 시 temperature를 낮게 설정하십시오. 0.2에서 0.4 사이의 값은 도구 이름과 인자 형식을 안정적으로 유지합니다. 에이전트가 마지막에 창의적인 텍스트를 생성한다면, 해당 마지막 호출에서만 temperature를 높일 수 있습니다. seed 매개변수는 전달되므로 디버깅 중 실행을 재현할 때 도움이 됩니다.

성인 소설 및 역할극 에이전트의 경우 동일한 패턴이 적용됩니다: 페르소나, 장면 규칙 및 도구를 시스템 메시지에 넣으세요. 이 모델은 합법적인 성인 사용에 대해 콘텐츠 거부 없이 답변하도록 조정되었습니다. 미성년자가 관련된 성 콘텐츠는 금지되어 있습니다.

Python으로 구현한 최소 에이전트 루프

아래 루프에는 하나의 도구만 있으며, 실제 데이터를 대신하는 사전 조회입니다. 모델이 도구 호출 없이 응답하거나 고정된 수의 단계가 지나면 중지됩니다.

import json
from openai import OpenAI

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")

NOTES = {
    "n1": "Invoice 114 was paid on March 3.",
    "n2": "Invoice 115 is overdue by 12 days.",
}

def search_notes(query):
    return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]

TOOLS = [{
    "type": "function",
    "function": {
        "name": "search_notes",
        "description": "Search internal notes by keyword",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."

def run(question, max_steps=6):
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]
    for step in range(max_steps):
        resp = client.chat.completions.create(
            model="uncensored",
            messages=messages,
            tools=TOOLS,
            temperature=0.3,
            max_tokens=500,
        )
        msg = resp.choices[0].message
        messages.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            try:
                args = json.loads(call.function.arguments)
                result = search_notes(args["query"])
            except Exception as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
    return "Stopped: step limit reached."

print(run("Which invoice is overdue?"))

주의해야 할 세 가지 세부 사항이 있습니다. 단계 제한은 혼란스러운 모델이 예산이 다 떨어질 때까지 루프를 돌지 않도록 합니다. try 블록은 잘못된 인수 문자열을 모델이 읽고 수정할 수 있는 오류 메시지로 변환합니다. 그리고 모든 도구 결과는 일치하는 tool_call_id와 함께 전송되며, 이를 통해 모델은 각 답변이 어떤 호출에 속하는지 알 수 있습니다.

429 응답 처리 및 동시성 처리

에이전트는 버스트형입니다. 계획자는 동시에 5개의 하위 작업을 분기할 수 있으며, 각각은 자체 루프를 실행합니다. 이때 속도 제한이 나타납니다.

전체 키는 8개의 동시 요청과 분당 300개의 요청을 허용합니다. 체험 키는 각각 2개와 60개를 허용합니다. 제한을 초과하면 API는 HTTP 429를 반환합니다. 오류 코드는 어떤 제한에 도달했는지 알려줍니다: 분당 요청 수에 대한 rate_limited, 동시성 초과에 대한 concurrency. 일시적 과부하 시에도 429와 Retry-After: 5 헤더가 반환됩니다.

이들 모두를 재시도 가능한 상태로 처리하십시오. 헤더에 명시된 초만큼 기다렸다가(헤더가 없으면 몇 초간 기다림), 요청을 다시 전송하십시오. 실패한 요청은 요금이 부과되지 않으므로 재시도 비용은 없습니다. 간단한 래퍼로 이 작업을 처리할 수 있습니다.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)

def chat_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(model="uncensored", **kwargs)
        except RateLimitError as err:
            wait = 5
            if err.response is not None:
                wait = int(err.response.headers.get("retry-after", 5))
            time.sleep(wait)
    raise RuntimeError("Still rate limited after 5 attempts")

429 오류를 피하려면 워커 풀에 한도를 설정하세요. 전체 키의 경우 8개의 세마포어가 적합합니다. 사용자 인터페이스에 스트리밍 응답을 보내는 경우, 스트림이 마지막 토큰이 도착할 때까지 동시성 슬롯을 차지하므로, 긴 답변을 읽는 느린 클라이언트는 전체 시간 동안 슬롯을 점유합니다. X-RateLimit-Limit-Requests 및 X-RateLimit-Limit-Concurrency 헤더를 읽으면 코드에서 사용하는 키에 따라 적응할 수 있습니다.

컨텍스트, 메모리 및 실행 비용

루프의 각 단계는 전체 대화 기록을 다시 전송합니다. 이는 채팅 API의 작동 방식이며, 도구 호출마다 입력 토큰이 증가한다는 의미입니다. 프롬프트가 2,000 토큰으로 시작하여 단계마다 1,000 토큰씩 증가하고, 단계당 300개의 출력 토큰을 생성하는 6단계 실행을 가정해 보세요.

  • 입력 토큰: 2,000 + 3,000 + 4,000 + 5,000 + 6,000 + 7,000 = 27,000
  • 출력 토큰: 6 x 300 = 1,800
  • 입력 비용: 27,000 x 0.15 / 1,000,000 = $0.00405
  • 출력 비용: 1,800 x 0.50 / 1,000,000 = $0.0009
  • 총계: 실행당 $0.00495

이러한 실행 1,000회의 비용은 $4.95입니다. 이는 에이전트가 여러 단계로 사고할 수 있을 만큼 저렴하지만, 용량 증가에는 주의가 필요합니다. 100,000 토큰의 용량이 있으므로, 장시간 실행되는 에이전트는 결국 컨텍스트 창을 채우게 되며, 그 크기의 프롬프트는 각 단계마다 입력 비용으로 100,000 x 0.15 / 1,000,000 = $0.015가 듭니다.

세 가지 습관이 이를 통제하는 데 도움이 됩니다. 웹 페이지의 첫 2,000자처럼 큰 도구 결과를 트랜스크립트에 넣기 전에 잘라내십시오. 기록이 임계값을 넘으면 오래된 단계를 하나의 짧은 메시지로 요약하십시오. 그리고 대화를 메모리로 사용하기보다 자체 데이터베이스에 영구적인 사실을 저장하십시오.

각 응답의 X-Balance-USD 헤더는 남은 크레딧을 보여주므로, 에이전트 감독자는 잔고가 최저선 아래로 떨어지면 실행을 중단할 수 있습니다. 크레딧은 $20부터 선불로 충전되며 만료되지 않습니다. 충전 보너스는 가격 페이지에서 확인하세요.

계획을 세우기 위한 솔직한 제한 사항

어떤 모델로 구축된 에이전트든 가드레일이 필요하며, 이 모델도 예외는 아닙니다. 다음 사항에 대비하세요.

  • 잘못된 인수. 모델이 유효하지 않은 JSON이거나 필수 필드가 누락된 도구 인수를 생성할 수 있습니다. 방어적으로 파싱하고 오류를 도구 결과로 반환하세요.
  • 잘못된 도구 선택. 짧고 명확한 도구 설명을 작성하세요. 두 도구가 비슷하게 들리면 모델이 혼동합니다. 흐름에 특정 함수 호출이 필요한 경우 tool_choice을 사용하여 해당 호출을 강제하세요.
  • 텍스트 전용. 이미지 입력/출력, 오디오, 임베딩, 파인튜닝 없음. 이러한 부분은 다른 곳에서 처리하고 결과를 텍스트로 전달하세요.
  • 단일 모델. 엔드포인트 뒤에는 단일 오픈 웨이트 모델이 있으며, 벤더 간 라우터가 아닙니다. 쉬운 단계에 더 작은 모델을 선택할 수 없습니다.
  • 파괴적인 도구. 에이전트에 삭제 또는 결제 도구를 부여할 때는 자체 코드에 확인 단계를 포함하십시오.

계획형 에이전트는 두 번째 패스의 이점도 얻습니다. 루프가 답변을 반환한 후, 모델이 본 도구 결과를 기준으로 답변을 검증하고 JSON 모드를 사용하여 결론과 미지원 주장 목록을 반환하도록 하는 한 번의 저렴한 호출을 더 수행할 수 있습니다. 이는 수백 개의 토큰을 추가하며, 도구 결과를 무시한 자신감 있는 답변이라는 가장 흔한 실패를 잡아냅니다.

마지막으로, 모든 단계를 로깅하세요. 메시지, 도구 인수 및 각 응답의 X-Request-Id 헤더를 저장하세요. 실행 중 오류가 발생하면 요청 ID를 통해 정확한 호출을 지목할 수 있으며, 로깅된 대화 기록은 어떤 도구 결과가 모델을 오도했는지 보여줍니다. 에이전트는 사용자가 나쁜 실행을 재생하고 한 번에 하나의 변경 사항을 적용할 수 있을 때 가장 쉽게 개선할 수 있습니다.

확정하기 전에 체험판으로 에이전트를 테스트하십시오. 신규 사용자는 $0.50의 크레딧을 청구할 수 있으며, 이는 위의 6단계 실행 기준으로 약 101회 풀 실행을 커버합니다(0.50 / 0.00495). 체험판의 동시 요청 2개를 염두에 두고 에이전트를 하나씩 실행하십시오. 서비스에 대한 더 넓은 시각을 얻으려면 토큰 기반 개요를 읽으십시오. 프롬프트는 학습에 사용되지 않습니다.

02

질문과 답변

API는 에이전트를 위한 도구 호출을 지원합니까?

네. 도구와 tool_choice를 받으며, 스트리밍 중에도 tool_calls를 반환하고 role이 tool인 메시지로 결과를 받습니다.

에이전트 호출을 병렬로 몇 개까지 실행할 수 있나요?

전체 키는 동시 8개 요청 및 분당 300개 요청을 허용합니다. 체험 키는 동시 2개 및 분당 60개 요청을 허용합니다.

에이전트가 429 오류를 받으면 어떻게 해야 하나요?

Retry-After 값을 기다리거나, 없다면 몇 초 후 재시도합니다. 거절된 요청은 요금이 부과되지 않습니다.

에이전트가 이미지나 오디오를 처리할 수 있나요?

아니요. 이 모델은 텍스트만 처리하므로 다른 미디어는 자체 도구로 처리하여 텍스트로 전달해야 합니다.

키는 양식 하나만 작성하면 받을 수 있습니다

계정을 생성하고 키를 복사한 후 기본 URL을 변경하세요. 설정은 이것으로 끝입니다.

API 키 받기