Structured Tools

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

LangChain은 단일 문자열 입력 제약을 넘어 다양한 자료형의 여러 인수를 받는 Structured Tools와 이를 기본 지원하는 StructuredChatAgent를 도입했다.

📌 핵심 요약

• LangChain 팀은 2023년 5월 2일 Structured Tools를 발표했으며, text-davinci-003·gpt-3.5-turbo·gpt-4의 발전을 도구 사용 제약을 재검토한 배경으로 설명했다.
• Structured Tools는 name, description, args_schema, _run·_arun으로 정의되며, Pydantic BaseModel 기반 args_schema는 입력 인터페이스를 전달하고 실행 전에 인수를 검증한다.
• 새로운 도구로 파일 쓰기·검색·이동·복사 등을 지원하는 파일 관리 툴킷과 웹사이트 이동·클릭·양식 제출·데이터 조회를 지원하는 상태 유지형 PlayWright 브라우저 툴킷을 공개했다.
• StructuredTool.from_function은 함수 시그니처에서 입력 스키마를 추론하며, BaseTool을 직접 상속하면 명시적 스키마, 환경 변수 기반 API 키 설정, 동기·비동기 실행을 구현할 수 있다.
• StructuredChatAgent와 langchain.experimental의 AutoGPT 에이전트는 구조화 도구를 지원한다. 기존 에이전트의 다중 인수 도구 사용에는 추가 수정이 필요하며, 기존 단일 문자열 도구는 새 에이전트에서도 사용할 수 있지만 JSON 직렬화 문자열 입력 도구는 수정이 필요할 수 있다.

🧩 주요 포인트

1. 단일 문자열에서 다양한 자료형의 여러 인수로 입력 확장 → 에이전트와 도구 사이에 더 복잡한 인터페이스를 표현할 수 있다.
2. args_schema의 인터페이스 전달과 실행 전 검증 → 도구 구현뿐 아니라 에이전트가 제공해야 할 입력도 명시적으로 정의한다.
3. 기존 단일 문자열 도구의 호환성과 다중 인수 도구의 제약 병존 → 도구 입력 형식과 에이전트 지원 여부에 따라 전환에 필요한 수정 범위가 달라진다.

🧠 상세 정리

1. 초기 도구 사용의 제약과 확장 배경

LangChain 팀은 2022년 11월 초기 출시부터 에이전트와 도구 활용을 설계의 중심에 두었으며, 도구 사용을 강조한 ReAct 논문에 기반한 체인을 초기에 구현했다고 설명한다. 당시 모델은 도구 이름과 해당 도구에 전달할 입력 문자열이라는 두 문자열을 생성했고, 에이전트는 한 차례에 도구 하나만 선택할 수 있었다. 이러한 제한은 모델이 기본적인 도구 선택과 입력 생성에도 어려움을 겪어 복수 도구 선택이나 복잡한 스키마 작성을 안정적으로 수행하기 어려웠기 때문이다. 이후 text-davinci-003, gpt-3.5-turbo, gpt-4의 발전을 계기로 기존 제약을 재검토했으며, 먼저 실행기의 각 단계에서 여러 행동을 계획하는 다중 행동 에이전트 프레임워크를 도입했다. 2023년 5월 2일 발표한 Structured Tools는 그 흐름을 이어 단일 문자열 입력 제약을 해소하고, 다양한 자료형의 여러 입력을 도구에 전달하도록 확장한 추상화다.

2. 도구의 역할을 전달하는 이름과 설명

Structured Tool은 에이전트가 수행할 수 있는 행동을 나타내며, 개발자가 제공한 함수를 감싸 에이전트가 해당 기능을 사용할 수 있도록 한다. 도구 객체는 이름인 name, 사용 지침인 description, 입력 정의인 args_schema, 실행 로직인 _run과 _arun으로 구성된다. 이름은 도구의 고유 식별자이자 기능을 전달하는 단서이므로, 원문은 축약형 GCTW보다 현재 날씨 조회 기능을 드러내는 GetCurrentWeather가 유용하다고 설명한다. 여러 도구를 함께 제공할 때는 AmazonSearch와 AmazonCurrentBalance처럼 이름에 공통 요소를 두어 에이전트가 도구 간 관련성을 추론하도록 도울 수도 있다. description은 언제, 왜, 어떻게 도구를 사용해야 하는지 간결하게 설명하는 역할을 하며, 필요한 경우 짧은 사용 예시나 반례를 포함할 수 있다.

3. 입력 스키마와 실제 실행 로직의 구분

args_schema는 도구에 전달할 인수와 각 인수의 자료형을 정의하는 Pydantic BaseModel이며, 일반적으로 감싼 함수의 시그니처를 바탕으로 구성된다. 첫 번째 역할은 에이전트가 어떤 정보를 입력해야 하는지 전달하는 것으로, 도구가 요구하는 인터페이스를 명시적으로 표현한다. 두 번째 역할은 실제 도구 기능을 실행하기 전에 입력값을 검증하는 것이며, 필요한 경우 추가적인 입력 검증 로직도 포함할 수 있다. _run과 비동기 실행용 _arun은 이 인터페이스 뒤에서 수행되는 실제 동작을 정의하고, 현재 시각 반환처럼 단순한 작업부터 메시지 전송이나 로봇 제어까지 다양한 기능을 담을 수 있다. 원문은 산술 연산, API 요청, 다른 LLM 체인 호출도 실행 로직의 예로 제시하며, 입력 계약과 도구 내부 기능을 구분해 설명한다.

4. 파일 관리와 상태 유지형 브라우저 도구

LangChain은 구조화 도구 기반 클래스와 함께 이를 상속한 파일 관리 툴킷과 웹 브라우저 툴킷을 새롭게 공개했다. 파일 관리 툴킷은 파일시스템 작업을 위한 것으로, 원문에는 write, grep, move, copy, list_dir, find가 포함 기능으로 제시되어 있다. 이 기능들은 파일 쓰기와 내용 검색뿐 아니라 파일 이동·복사, 디렉터리 목록 조회, 파일 찾기까지 다룬다. 웹 브라우저의 경우 기존에도 문서 로더용 브라우저가 있었지만, 이번에는 상태를 유지하는 공식 PlayWright 브라우저 툴킷을 에이전트용으로 제공한다고 설명한다. 에이전트는 이 툴킷으로 웹사이트에 이동하고 클릭하거나 양식을 제출하고 데이터를 조회할 수 있으며, 두 툴킷은 구조화 도구가 적용되는 구체적인 작업 영역을 보여준다.

5. 함수에서 구조화 도구를 만드는 방법

사용자 정의 도구를 가장 빠르게 만드는 방법으로 StructuredTool.from_function에 호출 가능한 함수를 전달하는 생성자가 소개된다. 예제의 get_huggingface_models 함수는 requests 라이브러리를 사용해 Hugging Face 모델 API에 GET 요청을 보내며, 선택적 path와 query_params를 받아 응답을 JSON으로 반환한다. API 키는 인증 헤더에 포함되고, 함수 설명에는 search, author, filter, sort와 같은 유효한 조회 매개변수가 명시되어 있다. StructuredTool.from_function은 함수 시그니처에서 args_schema를 추론하므로, 에이전트는 검색용 쿼리 매개변수와 하위 엔드포인트 접근용 경로를 제공할 수 있다는 정보를 전달받는다. 예제에서는 변환된 도구의 run에 query_params를 포함한 사전을 넘겨 gpt-j를 검색하며, 여러 입력을 하나의 문자열로 표현하지 않고 구조화된 형태로 전달하는 방식을 보여준다.

6. 직접 상속으로 설정과 실행을 세밀하게 제어

도구 정의를 더 세밀하게 제어하려면 BaseTool을 직접 상속할 수 있으며, 원문은 API 키를 환경 변수에서 자동으로 읽는 Hugging Face 도구를 예로 든다. 별도의 GetHuggingFaceModelsToolSchema는 기본값이 빈 문자열인 path와 선택적인 사전형 query_params를 정의하고, 각 필드에 설명을 부여한다. 도구 클래스는 BaseTool과 BaseSettings를 함께 상속해 이름, 설명, 입력 스키마, 기본 API 주소를 지정하며, api_key 필드는 HUGGINGFACE_API_KEY 환경 변수에 연결한다. _headers 속성은 API 키로 인증 헤더를 구성하고, 동기 _run은 requests를, 비동기 _arun은 aiohttp의 클라이언트 세션을 사용해 요청을 수행한다. 마지막 사용 예시는 이 도구의 인스턴스를 생성해 gpt-j 검색 조건을 전달하는 것으로, 자동 변환 방식과 같은 작업을 명시적인 스키마와 설정 및 실행 메서드로 구현한다.

7. StructuredChatAgent를 통한 도구 활용

LangChain은 구조화 도구를 기본적으로 사용할 수 있는 새로운 에이전트 클래스 StructuredChatAgent를 추가했다. 기존 에이전트는 기본 프롬프트와 출력 파서의 제약 때문에 별도의 수정 없이는 구조화 도구를 효과적으로 다루기 어렵다는 점이 도입 이유로 제시된다. 원문의 초기화 예제는 도구 목록과 temperature가 0인 ChatAnthropic 모델을 준비한 뒤, initialize_agent에 AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION을 지정한다. 모델 부분에는 다른 LLM을 사용할 수도 있다고 명시되어 있으며, 실제 사용할 도구는 예제의 빈 목록에 추가하는 형태다. 또한 langchain.experimental의 AutoGPT 에이전트도 이 도구들과 호환된다고 설명하므로, 구조화된 입력을 정의하는 일과 함께 이를 처리할 수 있는 에이전트를 선택하는 일이 사용 과정에 포함된다.

8. 기존 도구와 에이전트의 호환성 조건

FAQ는 구조화 도구라도 문자열 인수 하나만 받으면 기존 에이전트에서 사용할 수 있지만, 인수가 여러 개이면 일부 기존 에이전트에서 추가 수정 없이 직접 사용할 수 없다고 구분한다. 해당 목록은 zero-shot-react-description, react-docstore, self-ask-with-search, conversational-react-description, chat-zero-shot-react-description, chat-conversational-react-description이다. 단순 문자열 도구는 기존처럼 Tool 생성자와 @tool 데코레이터로 만들 수 있으며, BaseTool을 상속하고 단일 문자열 인수를 받는 도구도 문자열 도구로 취급된다. 반대 방향으로는 기존 문자열 BaseTool 도구를 구조화 도구용 새 에이전트에서 사용할 수 있고, Tool과 StructuredTool은 같은 기반 클래스를 공유하므로 구조화 도구 때문에 새 에이전트 실행기가 필요한 것은 아니라고 설명한다. 다만 JSON으로 직렬화한 문자열 입력을 기대하는 도구는 새 에이전트의 출력 파서에 맞춘 수정이 필요할 수 있으며, 원문은 더 복잡한 인터페이스를 지원하는 새 형식으로 변경하는 방안도 제시한다.

🧾 핵심 주장 / 시사점

• 다중 행동 에이전트는 단계마다 계획할 수 있는 행동 수를 확장하고, Structured Tools는 각 도구에 전달할 입력 구조를 확장한다는 점에서 서로 다른 제약을 해소한다.
• 도구의 이름과 설명은 에이전트의 선택과 사용을 안내하고, args_schema는 필요한 입력과 검증 조건을 전달하므로 도구 정의 자체가 에이전트와의 인터페이스 역할을 한다.
• 기존 도구의 재사용 가능성과 기존 에이전트의 다중 인수 처리 가능성은 별개다. 호환성을 판단할 때는 도구 입력 형식과 에이전트의 프롬프트·출력 파서를 함께 고려해야 한다.

✅ 액션 아이템

• Structured Tools 적용 대상의 입력이 단일 문자열인지 다양한 자료형의 여러 인수인지 확인.
• 입력 스키마 자동 추론과 명시적 정의의 필요에 따라 StructuredTool.from_function 또는 BaseTool 직접 상속 방식 선택.
• StructuredChatAgent 지원 여부와 기존 도구의 입력 형식을 바탕으로 다중 인수 및 JSON 직렬화 문자열 입력 도구의 수정 필요성 검토.

❓ 열린 질문

• 적용하려는 도구는 단일 문자열 입력으로 충분한가, 다양한 자료형의 여러 인수가 필요한가?
• args_schema를 함수 시그니처에서 추론하는 것으로 충분한가, 명시적 스키마와 추가 입력 검증이 필요한가?
• 기존 에이전트를 수정해 다중 인수 도구를 사용할 것인가, StructuredChatAgent를 사용할 것인가?