이 링크는 Notion 요구 사항으로 시작됩니다.
실제 시나리오는 다음과 같습니다. 마이크로서비스를 개발 중이며 기존 코드 베이스에 경보 모듈을 추가해야 합니다. 작업은 Notion으로 작성되며 요구 사항 분석부터 코드 제출까지 전체 프로세스를 완료하는 데 도움을 주는 에이전트가 필요합니다.
첫 번째 단계는 코드를 작성하는 것이 아니라 도구를 정의하는 것입니다. Notion 문서를 얻는 방법, 코드 베이스에 대한 검색 도구, 터미널 명령에 대한 실행 권한 및 Git 작업 인터페이스를 에이전트에게 알려야 합니다. 각 도구는 매개변수, 반환 값 및 오류 처리를 포함하는 API 호출 선언입니다. 이것은 Agent Engineering에서 가장 기본적이고 쉽게 간과되는 링크입니다: 도구 정의.
도구 정의가 불완전하면 에이전트가 첫 번째 수준에서 중단됩니다. 예를 들어 Notion API만 제공하고 인증 토큰이 제공되지 않은 경우 에이전트는 세 번 시도한 후 오류와 함께 종료됩니다. 많은 팀에서는 이러한 실패를 "AI 역량 부족"으로 간주합니다. 실제로 도구 레이어는 단단하지 않습니다.
핵심 루프: 계획, 호출, 관찰, 조정
도구가 준비되면 에이전트는 핵심 루프를 시작합니다. 지금 알람 모듈 작업을 예로 들어 보겠습니다.
- 계획: 에이전트는 Notion 요구 사항을 읽고 코드 검색 도구를 호출하여 현재 프로젝트 구조를 찾은 다음 실행 계획을 생성합니다(새 파일 생성, 구성 파일 수정, 종속성 추가).
- 호출 도구: 먼저
git pull을 실행하여 최신 코드를 가져온 다음 새 파일을 생성합니다. 여기서 핵심은 에이전트가 특정 명령을 생성하고 시스템이 실행을 위해 이를 터미널로 전달한다는 것입니다. - 관찰 결과: 파일이 성공적으로 생성되면 단말기는 경로 및 권한 정보를 반환합니다. 실패하면(예: 디렉터리가 존재하지 않음) 오류 코드가 반환됩니다. 에이전트는 관찰 내용을 기반으로 다음 단계를 조정해야 합니다.
- 조정: 에이전트는 실패할 경우 다시 계획합니다. 예를 들어 디렉터리를 먼저 만든 다음 파일을 만듭니다. 이 프로세스는 여러 번 반복될 수 있습니다.
이 사이클은 단순해 보이지만 세부사항에는 실패가 숨겨져 있습니다. 가장 일반적인 실수는 첫 번째 도구 호출이 성공한 후 상담원이 과신하여 확인을 건너뛰고 바로 다음 단계로 진행한다는 것입니다. 예를 들어 파일을 생성한 후 내용이 맞는지 확인하지 않고 직접 코드 포맷팅을 하여 빈 파일이 포맷되는 경우가 있었습니다.
컨텍스트 및 MCP: 에이전트가 길을 잃지 않도록 하세요.
루프를 사용하면 에이전트는 자신이 수행하는 작업도 기억해야 합니다. 컨텍스트 관리입니다.
각 도구 호출의 입력 및 출력은 컨텍스트 창에 기록됩니다. 문제는 컨텍스트 창의 상한이 GPT-4의 경우 128K 토큰, Claude의 경우 200K 토큰이라는 것입니다. 루프가 10번 이상 실행되면 컨텍스트가 기록 로그로 채워질 수 있습니다. 이 시점에서 에이전트는 "잊기" 시작합니다. 원래 요구 사항을 잊어버리거나 이미 완료된 작업을 반복할 수 있습니다.
해결책은 **MCP(모델 컨텍스트 프로토콜)**입니다. 이는 본질적으로 컨텍스트 정리 전략입니다. 현재 단계와 관련된 시스템 프롬프트, 도구 결과 및 요약만 유지하고 관련 없는 세부 정보는 삭제합니다. 구현 중에 슬라이딩 윈도우, 중요도 점수 등을 통해 컨텍스트 품질을 제어할 수 있습니다.
예를 들어, 실제로 각 사이클은 마지막 5개 도구 호출의 결과만 유지하고 그 이후의 결과는 한 문장 요약으로 압축됩니다. 이를 통해 에이전트는 30단계를 초과하는 복잡한 작업에서 90% 이상의 정확도를 유지할 수 있습니다.
권한 모델: 가장 쉽게 간과되는 함정
Agent Engineering와 일반 프로그래밍의 가장 큰 차이점은 에이전트에 부여하는 것은 코드 로직이 아닌 작업 권한입니다.
세 가지 질문에 답해야 합니다.
- 에이전트가 액세스할 수 있는 파일 시스템 경로는 무엇입니까?
- 에이전트는 어떤 터미널 명령을 실행할 수 있습니까(예:
rm -rf를 비활성화해야 함)? - 에이전트가 호출할 수 있는 외부 API는 무엇입니까(예: 프로덕션 환경 데이터베이스는 읽기 전용이어야 함)?
실패 시나리오는 매우 구체적입니다. 팀에서는 에이전트가 npm publish를 직접 실행하도록 허용했으며 그 결과 디버깅 프로세스 중에 완료되지 않은 패키지를 npm 공식 저장소에 게시했습니다. 이러한 유형의 문제는 신속한 엔지니어링으로는 해결할 수 없으며 도구 권한 수준에서 제어해야 합니다.
내 접근 방식은 도구 정의의 각 명령에 보안 ID를 바인딩하고 터미널에서 실행하기 전에 권한을 확인하는 것입니다. 예를 들어 파일 쓰기는 /src 및 /tests 디렉터리에만 허용되며 명령 블랙리스트에는 rm -rf, sudo, publish 등이 포함됩니다.
오류 복구: 작업 흐름을 중단하지 마세요.
도구 정의, 루프, 컨텍스트 및 권한이 있어도 에이전트는 여전히 실패합니다. 문제는 ** 실패할 경우 어떻게 해야 합니까? **
대부분의 구현에서는 예외가 발생하고 중지됩니다. 그러나 실제 개발 시나리오에는 더 많은 것이 필요합니다. 수동 개입 및 수정, 그리고 에이전트가 중단점에서 계속되도록 할 수 있습니다.
가능한 설계 중 하나는 "체크포인트 모드"입니다. 하위 작업이 완료될 때마다(예: 파일 생성, 테스트 통과) 현재 상태가 디스크에 저장됩니다. 후속 단계에서 에이전트가 실패하면 수동으로 이 체크포인트로 복원하고 문제를 수정한 후 후속 프로세스를 다시 시작할 수 있습니다.
다른 하나는 "명시적 인증 모드"입니다. 에이전트가 자동으로 해결할 수 없는 오류(예: API 인증 만료)가 발생하면 맹목적으로 재시도하는 대신 일시 중지하고 사람의 입력을 요청해야 합니다.
예를 들어 내 작업 흐름에는 "수동 개입 게이트"가 있습니다. 에이전트가 동일한 작업을 두 번 연속 수행하지 못하면 시스템은 개발자에게 새 자격 증명을 입력하거나 경로를 수정하라는 터미널 프롬프트를 표시합니다. 개발자가 터미널에 입력을 입력하면 에이전트가 계속 실행됩니다.
언제 에이전트를 포기해야 할까요?
Agent Engineering의 적용 가능한 경계는 무한하지 않습니다. 수동 코딩이나 기존 자동화가 더 적합한 몇 가지 상황이 있습니다.
- 보안에 매우 민감한 작업: 생산 환경 구성 수정, 금융 데이터의 실제 주문 작업 등.
- 사람의 판단이 필요한 결정: 인터페이스 디자인, 명명 충돌 해결 등.
- 비결정적 작업: 에이전트는 임의성을 포함하거나(예: 자동 생성된 비밀번호) 여러 차례의 수동 승인이 필요한 워크플로에 적합하지 않습니다.
- 초장기 주기 작업: 단일 작업이 1시간, 200단계를 초과하며 현재 상황 관리 기술로는 일관성을 유지하기 어렵습니다.
이러한 경계 밖에서는 Agent Engineering의 효율성이 크게 떨어집니다. 예를 들어 코드 리팩토링을 수행할 때 에이전트는 전체 프로젝트의 암시적 종속성을 이해할 수 없기 때문에 버그가 발생할 수 있습니다. 이 시점에서는 수동 리팩토링 + 단위 테스트라는 전통적인 접근 방식으로 돌아가야 합니다.
실행 가능한 체크리스트
실제 프로젝트에서 Agent Engineering를 사용하려는 경우 연습 후에 다듬은 목록은 다음과 같습니다.
- 도구 정의 무결성 검사: 각 도구의 입력/출력/오류 코드가 선언되어 있습니까?
- 최소화된 권한: 에이전트는 실제로 필요한 파일과 명령에만 액세스할 수 있습니다.
- 컨텍스트 정리 전략: 최대 보존 라운드 수(5~10라운드 권장)를 설정하고 초과 후 압축합니다.
- 실패 복구 메커니즘: 체크포인트 + 수동 개입 인터페이스.
- 모니터링 로그: 역추적을 용이하게 하기 위해 모든 도구 호출과 결정을 기록합니다.
- 샌드박스 테스트: 먼저 격리된 환경에서 실행하고 모든 것이 올바른지 확인한 다음 권한을 해제합니다.
이 목록은 일회성 구성이 아니며 완료되지만 각 작업 전에 검토해야 합니다. "지난주에는 괜찮았다"는 이유로 권한 확인을 건너뛰고, 그 결과 이번 주에 에이전트가 데이터베이스를 삭제하는 경우를 너무 많이 봤습니다.
다음 단계: 에이전트 엔지니어 되기
일반 개발자에서 에이전트 엔지니어로 변신하고 싶다면 이 기사의 다음 단계는 보다 체계적인 원본 유료 기사나 강좌가 되어야 합니다. 이 과정에서는 도구 호출 프로토콜을 설계하는 방법, 에이전트의 컨텍스트 창을 디버깅하는 방법, 프로덕션 수준 오류 복구 시스템을 구축하는 방법을 배우게 됩니다.
아직 댓글이 없습니다