에이전트 루프와 도구 호출(Tool Calling) 원리

🤔 에이전트가 파일을 고쳤다면 실제로 고친 것은 누구일까요?

에이전트에게 오류를 고쳐 달라고 하면 화면에 파일을 읽고, 명령을 실행하고, 다시 확인하는 과정이 줄줄이 지나갑니다. 모델이 컴퓨터를 직접 만지는 것처럼 보이지만, 앤트로픽 개발자 문서는 반대로 설명합니다. 모델은 스스로 아무것도 실행하지 않습니다. 모델이 하는 일은 어떤 도구를 어떤 값으로 불러 달라는 요청서를 쓰는 것까지이고, 파일을 열고 명령을 돌리는 것은 모델 바깥의 프로그램입니다.

AI 에이전트 뜻에서 에이전트는 결과를 보고 다음 행동을 정하는 과정을 되풀이한다고 설명했습니다. 이번 편은 그 되풀이가 실제로 어떤 왕복으로 이뤄지는지, 그리고 그 구조 때문에 무엇이 비용과 안전에 영향을 주는지를 봅니다.

🔑 에이전트 루프와 도구 호출의 정의

에이전트 루프는 모델이 도구 호출을 요청하면 프로그램이 실행하고 그 결과를 모델에게 돌려주는 왕복을 모델이 끝났다고 답할 때까지 되풀이하는 구조입니다.

도구 호출(tool calling)은 모델이 미리 알려 준 기능 목록 가운데 하나를 골라, 정해진 형식의 요청으로 불러 달라고 하는 동작입니다. 앤트로픽은 tool use, OpenAI는 function calling이라는 이름을 주로 쓰는데 가리키는 동작은 같습니다. 앤트로픽 문서도 tool use를 function calling이라고도 부른다고 적어 두었습니다.

🍳 주방장과 보조로 보는 관찰, 판단, 행동

주방장은 조리대 앞을 떠나지 않고 전표만 씁니다. "냉장고에서 달걀 두 개", "오븐 온도 확인"처럼 적어 넘기면 보조가 그대로 해 오고, 주방장은 가져온 재료와 온도를 보고 다음 전표에 적을 일을 정합니다. 에이전트 루프에서 주방장은 모델이고, 보조는 도구를 실행하는 프로그램입니다.

이 왕복을 세 단어로 줄이면 관찰, 판단, 행동입니다.

• 관찰: 도구 결과가 대화에 들어옵니다. 파일 내용, 명령 출력, 검색 결과가 여기에 해당합니다
• 판단: 모델이 지금까지의 대화와 결과를 보고 다음에 무엇을 할지 고릅니다
• 행동: 모델이 도구 호출 요청을 내보내고, 프로그램이 그것을 실행합니다

앤트로픽은 2025년 9월 에이전트 개발 도구를 소개하면서 같은 흐름을 맥락 모으기, 행동하기, 결과 확인하기의 반복으로 적었습니다. 이름은 달라도 결과를 보고 다음 행동을 정하는 순환이라는 점은 같습니다.

🔁 한 바퀴를 이루는 다섯 단계

앤트로픽 API 기준으로 루프 한 바퀴는 다음 순서로 돌아갑니다. 2026년 9월 28일 공식 문서 기준입니다.

1. 내 프로그램이 도구 목록과 사용자 메시지를 담아 모델에 요청을 보냅니다
2. 모델이 도구를 쓰기로 하면 응답의 stop_reason이 tool_use로 오고, 어떤 도구를 어떤 값으로 부를지 적힌 tool_use 블록이 붙습니다
3. 내 프로그램이 그 도구를 실행하고 결과를 tool_result 블록으로 만듭니다
4. 원래 메시지와 모델의 응답, 그리고 tool_result를 모두 담아 다시 요청합니다
5. stop_reason이 tool_use인 동안 2번부터 되풀이합니다

반복은 stop_reason이 다른 값으로 오면 끝납니다. end_turn은 모델이 최종 답을 냈다는 뜻이고, max_tokens는 출력 길이 한도에 걸려 멈췄다는 뜻입니다. 정해 둔 종료 문자열에 걸린 stop_sequence와 요청을 거절한 refusal도 있어서, 프로그램은 값마다 다르게 처리해야 합니다.

실제로 오가는 내용을 줄여 보면 이런 모양입니다. 날씨 조회 예시이며 값은 가상입니다.

tool_use_id가 요청과 결과를 짝지어 줍니다. 모델이 한 번에 도구 여러 개를 부르는 병렬 호출도 있어서, 결과마다 어느 요청의 답인지 이 번호로 맞춥니다.

📐 도구 정의에 들어가는 세 가지

모델은 도구의 속을 보지 못하고 정의에 적힌 글만 봅니다. 그래서 정의가 곧 모델이 아는 도구의 전부입니다.

설명이 모호하면 모델은 도구를 엉뚱한 때에 부르거나 필요할 때 부르지 않습니다. 앤트로픽은 에이전트 설계 글에서 이 부분을 에이전트와 컴퓨터 사이의 접점(ACI, agent-computer interface)이라 부르며 사람용 화면을 설계할 때만큼 공을 들이라고 권합니다. 같은 글은 상대 경로 때문에 실수가 나자 도구가 절대 경로만 받게 바꿨더니 실수가 사라졌다는 사례를 들며, 실수하기 어렵게 도구를 만드는 편이 낫다고 설명합니다.

필수 값이 비었을 때의 동작도 모델마다 다릅니다. 공식 문서는 오퍼스 계열이 빠진 값을 알아채고 되물을 가능성이 높고, 소네트 계열은 그럴듯한 값을 추측해 채울 수도 있다고 적고 있습니다. 지역을 말하지 않고 날씨를 물었는데 모델이 뉴욕을 넣어 호출하는 식입니다. 되돌리기 어려운 도구라면 값을 추측하지 말라는 지시를 함께 두는 편이 안전합니다.

🏠 내가 실행하는 도구와 서버가 실행하는 도구

도구는 실행되는 위치에 따라 두 종류로 나뉩니다.

서버 도구는 루프가 서버 안에서 돕니다. 한 번 요청에 검색을 여러 번 하고 결과를 읽은 뒤 답을 만들어 돌려주는데, 이 내부 반복에도 횟수 한도가 있습니다. 한도에 걸리면 pause_turn이 오고, 받은 응답을 포함해 다시 보내면 이어서 진행합니다.

MCP는 이 구조 위에 놓인 연결 규격입니다. 외부 서비스가 MCP 서버로 도구 목록을 내놓으면 에이전트 프로그램이 그 목록을 모델에게 넘기고, 모델이 호출을 요청하면 프로그램이 MCP 서버에 대신 실행을 맡깁니다. 모델 입장에서는 도구 정의가 하나 늘어난 것과 같습니다.

💰 한 바퀴 돌 때마다 입력이 길어지는 이유

모델은 앞의 대화를 따로 기억해 두지 않습니다. 그래서 4번 단계에서 원래 메시지와 앞선 응답, 도구 결과를 전부 다시 보냅니다. 도구 목록도 요청마다 함께 갑니다. 열 바퀴를 돌면 열 번째 요청에는 앞의 아홉 바퀴에서 오간 내용이 모두 들어 있습니다.

공식 문서가 밝힌 요금 구성은 이렇습니다.

• 도구 정의: 도구 이름과 설명과 형식이 입력 토큰으로 매번 들어갑니다
• 도구용 시스템 프롬프트: 도구를 쓰면 API가 자동으로 붙이는 안내문이 있고, 2026년 9월 28일 기준 클로드 오퍼스 5는 286토큰, 소네트 5는 354토큰, 하이쿠 4.5는 496토큰입니다(tool_choice가 auto일 때)
• 도구 호출과 결과 블록: 요청서와 결과가 대화에 쌓여 다음 입력이 됩니다

파일 내용이나 긴 명령 출력이 결과로 들어오면 대화가 빠르게 커집니다. 모델이 한 번에 볼 수 있는 양에는 한계가 있어서 컨텍스트 윈도우가 차면 오래된 내용을 요약하거나 비워야 합니다. 같은 앞부분을 반복해서 보내는 비용을 줄이는 방법은 프롬프트 캐시 편에서 다룹니다.

🛑 루프를 멈추게 하는 장치

모델이 end_turn을 내기 전까지 루프는 계속 돌 수 있습니다. 판단이 한 번 어긋나면 같은 도구를 같은 값으로 계속 부르기도 해서, 에이전트를 만드는 쪽은 멈추는 장치를 따로 둡니다.

• 최대 반복 횟수: 몇 바퀴를 넘기면 멈추고 사람에게 알립니다
• 승인이 필요한 도구: 파일 삭제, 결제, 발송처럼 되돌리기 어려운 도구는 실행 전에 사람의 승인을 받습니다. 클로드 코드의 권한 설정과 훅이 이런 장치입니다
• 실패를 결과로 돌려주기: 도구가 실패하면 오류 메시지를 그대로 tool_result에 담아 돌려줍니다. 모델이 오류를 보고 방법을 바꿀 수 있어야 같은 실패를 되풀이하지 않습니다
• 결과 확인 단계: 앤트로픽은 검사 규칙(린트), 화면 캡처, 다른 모델의 평가를 결과 확인 방법으로 들고, 규칙 기반 확인이 가장 믿을 만하다고 설명합니다

⚠️ 도구를 붙일 때 자주 하는 실수

• 도구 설명을 한 줄로 끝냅니다: 비슷한 도구가 두 개 있으면 모델은 설명으로만 둘을 구분합니다. 언제 쓰고 언제 쓰지 않는지까지 적습니다
• 도구를 너무 많이 붙입니다: 도구 정의는 매 요청 입력에 들어가므로 쓰지 않는 도구도 비용과 판단 부담을 늘립니다
• 도구가 필요 없는 일에 붙입니다: 공식 문서는 요약, 번역, 일반 지식 질문처럼 모델이 학습한 내용만으로 답할 수 있는 일에는 도구 왕복이 필요 없다고 적고 있습니다

❓ 자주 묻는 질문

도구 호출과 function calling은 같은 말인가요?

같은 동작을 가리킵니다. 앤트로픽은 tool use, OpenAI는 function calling이라는 이름을 주로 쓰고, 앤트로픽 문서도 tool use를 function calling이라고도 부른다고 적어 두었습니다. 모델이 정해진 형식으로 기능 호출을 요청하고 바깥 프로그램이 실행한다는 구조는 같습니다.

모델이 인터넷을 직접 검색하는 경우도 있나요?

웹 검색 같은 서버 도구를 켜면 앤트로픽 서버가 검색을 실행하고 결과를 응답에 담아 줍니다. 이때도 모델이 검색을 요청하고 서버 프로그램이 실행한다는 구조는 같고, 달라지는 것은 실행하는 쪽이 내 프로그램이 아니라 앤트로픽 서버라는 점입니다.

루프가 끝나지 않고 같은 호출을 되풀이하면 어떻게 하나요?

최대 반복 횟수를 두고, 넘기면 멈춘 뒤 사람에게 상황을 알리게 만듭니다. 같은 도구를 같은 값으로 연달아 부르면 도구 결과나 오류 메시지가 모델에게 제대로 전달되는지부터 확인합니다. 실패가 결과로 돌아가지 않으면 모델은 무엇이 잘못됐는지 모른 채 같은 요청을 다시 보냅니다.

도구 결과를 짧게 줄여서 돌려줘도 되나요?

줄여도 됩니다. 결과가 길수록 다음 요청의 입력이 커지므로 필요한 부분만 돌려주는 편이 비용과 속도에 유리합니다. 다만 모델이 판단에 쓸 정보까지 잘라 내면 엉뚱한 다음 행동이 나오므로, 오류 메시지와 핵심 값은 남깁니다.

📋 3줄 요약

1. 에이전트 루프는 모델이 도구 호출을 요청하면 프로그램이 실행하고 그 결과를 돌려주는 왕복을 모델이 끝났다고 답할 때까지 되풀이하는 구조입니다.

2. 앤트로픽 API에서는 응답의 stop_reason이 tool_use인 동안 도구를 실행해 tool_result로 돌려보내고 end_turn 같은 다른 값이 오면 반복을 멈춥니다.

3. 한 바퀴를 돌 때마다 도구 정의와 그때까지의 대화와 도구 결과를 전부 다시 보내므로 단계가 늘수록 입력 토큰과 비용이 함께 늘어납니다.

📚 참고 자료

• 앤트로픽 개발자 문서, How tool use works: https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works
• 앤트로픽 개발자 문서, Tool use with Claude: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
• 앤트로픽, Building effective agents: https://www.anthropic.com/engineering/building-effective-agents
• 앤트로픽, Building agents with the Claude Agent SDK: https://claude.com/blog/building-agents-with-the-claude-agent-sdk