ReAct와 도구 호출 반복 이해하기

모델이 외부 기능을 사용하는 방법

언어 모델은 학습된 문장을 바탕으로 답을 만들지만 현재 날씨, 사내 데이터베이스나 사용자의 파일을 저절로 읽지는 못합니다. 텍스트로 “파일을 삭제했다”고 답하는 것과 실제 파일 시스템에서 삭제를 수행하는 것도 전혀 다른 일입니다. 에이전트가 외부 세계와 상호작용하려면 모델의 판단을 프로그램이 실행할 수 있는 명시적인 요청으로 바꾸는 경계가 필요합니다.

모델은 사용할 수 있는 도구의 이름, 설명과 입력 스키마를 받고 필요할 때 도구 호출(Tool Calling)을 구조화된 데이터로 제안합니다. 예를 들어 자연어 문장 대신 get_weather라는 도구 이름과 {"city": "Seoul"}이라는 인자를 반환합니다. 애플리케이션은 제안을 검증하고 허용된 경우에만 함수를 실행하며, 성공값이나 오류를 다시 모델에 전달합니다. 모델은 실행을 제안할 뿐 운영체제 권한을 직접 갖지 않는다는 구분이 핵심입니다.

그림: 판단·도구 실행·관찰이 끝낼 조건까지 반복됩니다.

ReAct는 판단, 행동과 관찰을 번갈아 사용해 다음 단계를 정하는 패턴입니다. 현재 도구 호출 API는 모델의 내부 추론 전문을 애플리케이션에 노출하지 않아도 도구 이름과 인자, 결과를 구조화된 메시지로 주고받을 수 있습니다. 중요한 것은 숨겨진 생각을 출력시키는 일이 아니라 관찰 가능한 행동 제안과 결과를 정확히 연결하는 일입니다.

한 번의 반복은 사용자 요청, 모델의 도구 제안, 하네스의 검증과 실행, 도구 결과 관찰, 모델의 다음 판단 순서로 진행됩니다. 결과만으로 답할 수 있으면 종료하고, 추가 정보가 필요하면 다른 도구를 제안합니다. 이 흐름 때문에 도구 오류도 모델이 읽을 수 있는 형태로 돌려주되, 비밀값이나 내부 스택 전체를 그대로 노출해서는 안 됩니다.

도구는 일반 함수로 시작하기

다음 함수는 입력과 반환 형식을 명확히 한 작은 도구입니다.

def get_weather(city: str) -> dict:
    allowed = {"Seoul": {"temperature": 21, "condition": "sunny"}}
    if city not in allowed:
        return {"error": "unsupported city"}
    return allowed[city]

에이전트 하네스는 모델이 get_weather와 {"city": "Seoul"}을 제안했을 때 인자를 검사하고 함수를 호출합니다. 반환 딕셔너리를 관찰 메시지에 넣으면 모델이 최종 자연어 답을 만들 수 있습니다.

좋은 도구는 한 가지 책임을 가지며 이름과 입력 필드가 구체적입니다. “모든 시스템을 관리하는 도구”보다 “도시의 현재 날씨를 읽는 도구”가 모델도 선택하기 쉽고 권한도 제한하기 쉽습니다. 반환값 역시 긴 설명문보다 성공 여부, 데이터와 오류 코드를 구분한 구조가 다음 판단과 테스트에 유리합니다.

반복에 안전장치 넣기

도구 설명은 모델의 선택을 돕지만 보안 경계가 아닙니다. 허용 목록, 인자 스키마, 사용자 권한과 실행 시간 제한을 코드에서 검사합니다. 조회 도구와 변경 도구의 권한을 분리하고, 파일 경로나 URL처럼 공격 표면이 넓은 인자는 허용 범위를 좁힙니다. 모델이 만든 인자를 그대로 셸 명령으로 이어 붙여서는 안 됩니다.

최대 반복 횟수, 전체 시간과 비용 한도를 정하고 같은 도구의 반복 호출도 감지해야 합니다. 도구가 실패했을 때 재시도할 오류와 즉시 중단할 오류를 구분하며, 부분적으로 성공한 쓰기 작업은 멱등성 키나 실행 기록으로 중복을 막습니다. 결제, 삭제나 외부 전송은 최종 인자를 사람이 확인한 뒤 실행하도록 분리할 수 있습니다.

실행 순서가 항상 같은 작업은 모델에게 도구 선택을 맡기기보다 일반 워크플로로 작성하는 편이 단순합니다. 사용자의 요청과 관찰 결과에 따라 필요한 도구가 달라질 때 도구 호출 에이전트의 가치가 생깁니다. 즉, 도구가 있다는 이유만으로 에이전트가 필요한 것은 아닙니다.

복잡한 반복은 LangGraph 상태 머신으로 명시하고, 서로 다른 도구 제공자를 표준화할 때는 MCP를 검토합니다.

참고 문서

• LangChain 공식 문서 — Agents
• LangChain 공식 문서 — Tools