KO ▾
API 키 받기

LangChain 에이전트 AI 문서: 도구 및 JSON 모드

대부분의 LangChain 에이전트 AI 문서는 벤더의 자체 모델 클래스를 가정하지만, base URL을 설정하면 ChatOpenAI를 사용하여 모든 OpenAI 호환 엔드포인트를 사용할 수 있습니다. 이 가이드는 LangChain을 이 API에 연결하고 도구 호출 에이전트를 단계별로 구축합니다.

업데이트

주요 포인트

  • base_url을 이 API로 설정하고 모델을 uncensored로 설정하여 ChatOpenAI를 사용하세요.
  • 도구 호출과 JSON 모드가 지원되므로 bind_tools와 response_format은 문서화된 대로 작동합니다.
  • 에이전트 루프를 제한하고 도구 인수를 검증하며 전체 키에서 max_concurrency를 8 이하로 유지하세요.
  • SSE를 통한 스트리밍은 끝에 토큰 사용량을 반환하므로 각 에이전트 실행의 비용을 추적하는 데 도움이 됩니다.
루프 트랙을 따라 도구 스테이션을 통과하는 큐브를 이동하는 로봇 팔로, LangChain 에이전트 루프를 나타냅니다

시작하기 전에 필요한 항목

LangChain 에이전트 AI 문서를 읽고 있는 중이고 모델이 예제에 있는 벤더의 것이 아닐 때 어떤 변화가 있는지 궁금하다면, 답은 매우 적습니다. LangChain의 에이전트는 루프입니다: 모델이 대화를 읽고, 도구를 호출할지 여부를 결정하고, 코드가 도구를 실행하며, 결과가 최종 답변을 생성할 때까지 모델로 다시 돌아갑니다. 모델 엔드포인트는 도구 호출이 포함된 채팅 완료만 지원하면 되며, 이 API는 이를 지원합니다.

세 가지가 필요합니다: 키 페이지의 API 키, Python 3.10 이상, 그리고 아래 패키지입니다. base URL은 https://api.unlimitedaiapi.com/v1이고 모델 ID는 uncensored입니다. 이는 독립적인 공급자가 운영하는 하나의 오픈 웨이트 모델이므로 선택할 모델 목록이 없으며, GET /v1/models은 클라이언트 검색을 위해 이를 반환합니다.

pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"

단계 1: ChatOpenAI를 엔드포인트에 연결

LangChain의 ChatOpenAI 클래스는 사용자 지정 base_url을 받습니다. invoke, stream, batch 및 async 변형을 포함하여 나머지 모든 것은 동일하게 유지됩니다.

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0.2,
)

print(llm.invoke("Reply with one short sentence.").content)

이것이 문장을 출력하면 인증, 라우팅 및 모델 이름이 모두 정확합니다. 인증은 클래스가 자동으로 추가하는 표준 Authorization: Bearer 헤더입니다. 흔한 실수는 base URL에서 /v1을 누락하는 것으로, 이는 보통 첫 번째 호출이 실패하게 만듭니다.

단계 2: 도구 정의 및 바인딩

도구는 docstring이 있는 일반 Python 함수입니다. docstring과 타입 힌트는 모델이 보는 스키마가 되므로, 새로운 동료에게 함수를 설명하는 것처럼 작성하세요.

import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])

ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)

출력된 목록에는 이름이 get_order_status이고 인수가 {"order_id": "A100"}인 호출이 포함됩니다. 내부적으로 LangChain은 채팅 완성 요청의 tools 배열에 함수를 보내며, API는 tools, tool_choice 및 스트리밍된 tool_calls을 지원합니다. 도구 호출을 강제하려면 bind_tools에 tool_choice을 전달하세요.

온도가 낮은 이유

에이전트는 여러 모델 호출을 연결하므로, 하나의 잘못된 인수로 인해 실행이 어긋날 수 있습니다. 0에서 0.2 사이의 temperature는 도구 선택을 더 반복 가능하게 만듭니다. 더 다양한 텍스트를 원한다면 최종 답변 단계에서만 높여야 합니다.

단계 3: 에이전트 루프 실행

루프를 직접 작성하면 15줄이 필요하며 각 단계에서 정확히 무슨 일이 일어나는지 보여줍니다. 이는 문제가 생겼을 때 도움이 됩니다. 도구 결과는 ToolMessage 객체로 모델에 다시 전달되며, 이는 네트워크를 통해 role: "tool" 메시지가 됩니다.

import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))

messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5):                      # hard cap on loop length
    ai = llm_with_tools.invoke(messages)
    messages.append(ai)
    if not ai.tool_calls:
        break
    for call in ai.tool_calls:
        result = tools[call["name"]].invoke(call["args"])
        messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))

print(ai.content)

range(5)에 주목하세요. 단계 제한이 없는 에이전트는 혼란스러운 도구 결과로 무한히 루프를 돌 수 있으며, 모든 반복은 지금까지의 전체 대화에 대한 입력 토큰 비용이 듭니다. 5는 간단한 작업에 대한 합리적인 상한선입니다. 의도적으로 높여야 합니다.

사전 구축된 에이전트 헬퍼 사용

최근 LangChain 버전에는 이 루프를 대신 실행하는 도우미가 포함되어 있습니다. 이름과 import 경로는 릴리스 간에 변경되었으므로 설치된 버전의 문서와 대조하여 확인하세요. 현재 1.x 라인에서는 다음과 같습니다:

import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)

agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)

표준 패턴이 필요할 때는 헬퍼를 사용하고, 사용자 지정 종료 규칙, 단계별 로깅 또는 모델이 보기 전에 필터링하려는 도구 결과가 필요할 때는 직접 작성한 루프를 사용하세요.

JSON 모드를 사용한 구조화된 출력

에이전트는 종종 계획, 분류 또는 추출된 필드의 목록과 같은 데이터를 다른 코드에 전달해야 합니다. JSON 모드는 응답을 유효한 JSON 객체로 강제합니다. LangChain에서는 bind을 통해 전달할 수 있습니다:

import json
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})

msg = json_llm.invoke(
    "Extract the city and country from: 'I moved to Lyon, France last spring.' "
    "Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))

프롬프트에 JSON이라는 단어를 언급하고 예제와 같이 기대하는 키를 설명하세요. JSON 모드는 스키마가 아닌 구문을 보장하므로 여전히 파싱된 객체(예: Pydantic 사용)를 검증하고 누락된 키를 처리하세요.

에이전트 실행의 제한, 스트리밍 및 비용

에이전트는 짧은 시간 내에 많은 호출을 하므로 계정 제한이 단순한 채팅봇보다 더 중요합니다. 일반 키는 동시 요청 8개와 분당 300개의 요청을 허용합니다. 체험 키는 2개와 60개를 허용합니다. batch로 분산하거나 여러 에이전트를 동시에 실행하는 경우 구성에서 병렬성을 제한하세요:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
    print(a.content)

체험 키에서는 8 대신 2를 사용하세요. 대화형 에이전트의 경우 llm.stream(...)은 생성되는 대로 SSE를 통해 토큰을 반환하고, 사용량 숫자는 스트림 끝에 도착합니다.

비용은 쉽게 추정할 수 있습니다. 5단계 실행에서 평균적으로 각 단계당 4,000개의 입력 토큰과 300개의 출력 토큰을 사용하면 총 20,000개의 입력 토큰과 1,500개의 출력 토큰이 사용되며, 이는 1M 토큰당 $0.15 및 $0.50의 가격으로 실행당 $0.003 + $0.00075 = $0.00375입니다. 가격 책정 페이지에는 요금이 나와 있으며, 문서에는 단일 실패 호출을 추적하기 위한 X-Request-Id을 포함한 요청 매개변수 및 헤더가 나열되어 있습니다.

모델이 사용할 수 있는 도구 설계

대부분의 에이전트 실패는 루프가 아닌 도구에서 비롯됩니다. 몇 가지 규칙은 모든 모델에 도움이 됩니다:

  • 각 도구를 좁게 유지하세요. 이름이 get_order_status인 도구는 자유 형식 텍스트를 받는 database_query보다 더 잘 작동합니다.
  • 간단한 인수 유형을 사용하세요: 문자열, 정수 및 짧은 열거형입니다. 깊게 중첩된 객체는 모델이 필드를 잘못 가져올 수 있는 방법을 더 많이 제공합니다.
  • 짧고 평이한 결과를 반환하세요. 대화에 50,000자를 덤프하는 도구는 컨텍스트 창을 채우고 이후 모든 단계의 비용을 증가시킵니다.
  • 실행을 종료하는 예외를 발생시키는 대신 "order_id는 A100 형식이어야 합니다"와 같은 텍스트로 오류를 반환하세요.

확장하기 전에 $0.50 체험 크레딧으로 몇 가지 실제 프롬프트에 대해 에이전트를 테스트하세요. 신규 사용자는 키 페이지에서 한 번의 클릭으로 이를 얻으며, 이는 7일 동안 유효합니다.

먼저 확인할 함정

  • 도구 호출이 표시되지 않음. docstring을 구체적으로 만들고 온도를 낮추거나 tool_choice로 호출을 강제하세요.
  • 잘못된 인수. 도구 내에서 검증하고 명확한 오류 문자열을 반환하여 모델이 다음 단계에서 스스로 수정할 수 있게 하세요.
  • 컨텍스트 증가. 창은 응답을 포함하여 100,000개의 토큰입니다. 창이 가득 차기 전에 오래된 도구 출력을 정리하세요.

질문과 답변

어떤 LangChain 클래스가 이 API와 호환되나요?

langchain-openai의 ChatOpenAI입니다. base_url을 https://api.unlimitedaiapi.com/v1, 모델에 uncensored로 설정하고 api_key로 키를 전달하세요.

API는 에이전트를 위한 도구 호출을 지원하나요?

네. tools 및 tool_choice 매개변수를 받아들이고, 스트리밍 중에도 tool_calls를 반환하며, role tool인 메시지로 결과를 다시 받습니다.

LangChain은 이 API를 통해 구조화된 출력을 구문 분석할 수 있나요?

네, JSON 모드를 통해 가능합니다: response_format을 json_object 유형으로 설정하세요. 유효한 JSON 구문을 보장하므로 필드를 직접 검증하세요.

동시에 몇 개의 에이전트를 실행할 수 있나요?

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

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

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

API 키 받기