AI 에이전트는 도구 실행 뒤 어떻게 다음 작업을 이어 갈까?

모델의 도구 호출은 실행 요청이다

AI가 파일을 읽겠다고 답했다고 해서 파일이 열린 것은 아니다. 클라이언트 도구 방식에서는 모델이 함수 이름과 인자를 보내고, 애플리케이션이 해당 함수를 실행한 뒤 결과를 돌려준다. 이 연결을 맡는 코드가 하네스의 핵심이다.

최근 GeekNews에 소개된 Harness Engineering 101은 그 구조를 HTTP 요청과 Python 코드에서부터 설명하는 교재다. 16개 장을 거치며 약 300줄 규모의 교육용 에이전트를 키워 간다. 개발자에게 주는 가치는 짧은 코드의 성능 기록보다 모델 밖에서 일어나는 일을 읽을 수 있다는 데 있다.

3장의 도구 계약에서는 사용 가능한 함수의 이름·설명·입력 형식을 모델에 보낸다. 모델이 read_file을 요청하면 실제 파일 읽기는 Python 함수가 수행한다. 반환된 텍스트를 모델이 받아야 다음 판단도 파일 내용에 근거할 수 있다.

한 번의 요청을 끝내기 위해 모델을 여러 번 부른다

첫 단계의 결과가 있어야 다음 행동을 고를 수 있는 작업에는 반복이 필요하다. 예를 들어 파일 목록을 얻은 뒤 특정 파일을 읽으려면, 첫 실행 결과가 다음 모델 호출에 들어가야 한다. 한 번 실행하고 사용자 입력을 기다리는 프로그램은 이 연결을 자동으로 이어 주지 못한다.

4장은 모델 호출, 도구 실행, 결과 추가를 반복하는 방식으로 이 문제를 푼다. 한 번의 사용자 요청 안에서 모델과 도구가 여러 차례 왕복할 수 있다.

공개된 v3_agent.py는 한 응답의 여러 도구 요청을 순서대로 실행한 뒤 결과를 묶어 돌려준다. 각 결과에는 원래 요청의 ID가 붙는다. 반복 상한은 50회다. 짧은 루프에도 메시지 순서, 요청과 결과의 대응, 중단 지점이 들어 있다.

응답이 멈춘 이유를 성공 여부로 바꾸면 안 된다

예제의 종료 분기는 학습을 위해 단순하다. stop_reason이 tool_use가 아니면 바로 반환한다. 따라서 이 버전은 응답이 길이 제한으로 잘린 경우를 별도로 복구하지 않는다.

Anthropic의 공식 종료 이유 문서는 end_turn을 자연스러운 응답 종료, max_tokens를 출력 한도 도달로 구분한다. 후자는 출력 한도를 늘리거나 응답을 이어 가는 처리가 필요하다. end_turn도 모델 응답의 종료를 뜻하므로, 테스트 통과나 파일 수정 성공은 실제 도구 결과에서 판단해야 한다.

오류를 돌려주는 방식도 다음 행동에 영향을 준다. 교재는 실패 원인을 숨기지 않고 모델에 전달해야 한다고 설명한다. v3는 예외를 문자열로 반환하지만, 도구 결과에 is_error 표시를 붙이거나 명령의 종료 코드를 별도 필드로 전달하지는 않는다. 학습용 예제를 옮겨 쓸 때는 이런 처리 범위까지 읽어야 한다.

프레임워크가 처리할 일과 직접 구현할 일을 구분한다

에이전트가 도구를 부르는 원리를 배우려면 이 교재의 3·4장과 구현 파일을 함께 읽는 것이 좋은 출발점이다. 도구 요청이 생겼을 때 어떤 코드가 실행되는지, 그 결과가 다음 메시지에 남는지 직접 따라갈 수 있다.

운영할 앱에서는 대화 저장과 중단 후 복구도 필요해진다. Cloudflare의 하네스 문서는 모델 호출·도구 제어·메시지 보존을 하네스의 역할로 설명하고, 상태·세션·지속 실행을 제공하는 런타임과 구분한다. 직접 루프를 짜는 선택은 이 동작을 통제할 수 있게 하지만, 필요한 처리도 직접 맡는 선택이다.

프레임워크를 고를 때는 도구 호출 이후의 처리도 확인해야 한다. 결과를 무엇으로 저장하고, 어떤 실패에서 다시 시도하며, 언제 사용자에게 제어를 돌려줄 것인지가 실제 에이전트의 동작을 결정한다.