첫 AI 에이전트 30분 만에 만들기

첫 AI 에이전트를 30분에 만드는 비결은 코드를 빨리 짜는 것이 아니라 범위를 극단적으로 좁히는 것입니다. 일 하나, 도구 하나, 검증 기준 하나로 시작하면 실제로 30분 안에 동작하는 것을 만들 수 있습니다. 순서는 정해져 있습니다. 할 일을 좁히고, 완료 조건을 먼저 적고, 모델·도구·검증으로 이루어진 루프를 돌리고, 실패했을 때 무엇을 할지 정하고, 마지막에 로그를 남깁니다. 아래는 그 30분을 5분 단위로 쪼갠 절차입니다.

30분 안에 무엇을 만들 수 있나?

만들 수 있는 것은 "입력 하나를 받아, 도구를 한두 번 쓰고, 결과가 기준을 만족하는지 확인한 뒤 끝내는" 작은 루프입니다. 예를 들면 특정 폴더의 문서를 읽어 정해진 형식의 요약 파일을 만들고, 그 파일에 필수 항목이 다 들어갔는지 확인하는 정도입니다.

만들 수 없는 것은 여러 역할이 협업하는 멀티에이전트 구조나, 장기 기억을 갖춘 시스템입니다. 그것들은 작은 루프 하나가 안정적으로 도는 것을 확인한 다음에 붙이는 것입니다. 처음부터 큰 구조를 그리면 30분이 아니라 3일이 걸리고, 그마저도 어디가 틀렸는지 알기 어려워집니다.

0~5분: 할 일 하나로 좁히기

가장 중요한 5분입니다. 후보를 여러 개 떠올린 뒤, 다음 세 조건을 모두 만족하는 것 하나만 남깁니다.

• 입력이 명확합니다. 무엇을 주면 시작되는지가 한 문장으로 적힙니다.
• 결과가 눈에 보입니다. 파일, 표, 메시지처럼 만들어졌는지 확인할 수 있는 형태여야 합니다.
• 실패해도 안전합니다. 첫 에이전트는 읽기와 새 파일 생성까지만 하게 두고, 기존 데이터 삭제·수정·외부 전송은 넣지 않습니다.

세 번째 조건을 타협하지 마시길 권합니다. 첫 에이전트는 반드시 틀린 행동을 합니다. 그 틀린 행동이 되돌릴 수 있는 범위 안에서 일어나야 배울 수 있습니다.

5~10분: 완료 조건을 먼저 적기

코드보다 먼저 적어야 하는 것은 "무엇을 보면 성공이라고 판단할 것인가"입니다. 이것이 없으면 나중에 에이전트가 "완료했습니다"라고 말할 때 확인할 방법이 없습니다.

완료 조건은 사람이 아니라 프로그램이 판정할 수 있는 형태여야 합니다. "요약이 잘 되었다"는 조건이 아니고, "출력 파일이 존재하고, 필수 항목 4개가 모두 비어 있지 않다"는 조건입니다. 좋은 판정 기준은 참·거짓으로 떨어집니다.

이때 함께 적을 것이 하나 더 있습니다. 중단 조건입니다. 몇 번 시도해도 안 되면 멈출 것인지 정합니다. 3회 정도가 무난한 출발점입니다. 중단 조건이 없는 루프는 실패했을 때 무한히 돌면서 토큰만 소모합니다.

10~20분: 루프 만들기

이제 코드를 씁니다. 구조는 단순합니다. 목표를 모델에 주고, 모델이 도구를 호출하겠다고 하면 실행해서 결과를 돌려주고, 검증을 통과하면 끝냅니다.

type Result = { ok: boolean; note: string };

async function runAgent(goal: string, maxSteps = 3): Promise<Result> {
  const history: string[] = [goal];

  for (let step = 0; step < maxSteps; step++) {
    const action = await model.decide(history);   // 다음에 할 일 결정
    const output = await tools.run(action);        // 도구 실행
    history.push(output);

    const check = verify(output);                  // 5~10분에 정한 완료 조건
    if (check.ok) return check;

    history.push(`검증 실패: ${check.note}. 다시 시도하세요.`);
  }

  return { ok: false, note: "최대 시도 횟수 초과 — 사람 확인 필요" };
}

핵심은 verify가 모델 바깥에 있다는 점입니다. 모델에게 "잘 됐는지 확인해라"라고 시키는 것과, 코드가 실제 파일이나 반환값을 확인하는 것은 전혀 다릅니다. 전자는 자기 채점이고 후자가 검증입니다.

도구 연결이 번거롭게 느껴진다면 MCP처럼 표준화된 연결 규격을 쓰는 방법도 있습니다. 다만 첫 30분에는 함수 하나를 직접 호출하는 편이 이해가 빠릅니다.

20~30분: 실패 처리와 로그

루프가 돌기 시작하면 남은 10분으로 실패 처리를 채우고 한 번 돌려 봅니다. 검증에 실패했을 때 선택지는 세 가지뿐입니다.

1. 재시도 — 같은 계획으로 다시 합니다. 일시적 오류(네트워크, 형식 오류)에 적합합니다.
2. 계획 수정 — 실패 내용을 맥락에 넣고 다른 방법을 시도하게 합니다. 위 코드가 취하는 방식입니다.
3. 사람에게 넘기기 — 판단이 필요하거나 되돌리기 어려운 경우입니다.

이 분기를 명시하지 않으면 에이전트는 대개 1번만 반복하다 시간을 씁니다. 특히 실패 사유를 다음 회차에 전달하지 않으면 모델은 같은 계획을 그대로 다시 세웁니다. 그리고 중단 후 반환값에는 "왜 멈췄는지"가 담겨야 합니다. 위 코드의 note가 그 자리입니다. 실패를 성공처럼 반환하는 것이 실패 자체보다 위험합니다.

여기까지 되면 마지막은 실행과 기록입니다. 실제 입력으로 한 번 돌리고, 각 회차에서 모델이 무엇을 하려 했고 도구가 무엇을 돌려줬는지 파일이나 콘솔에 남깁니다. 회차 번호, 선택한 도구, 검증 결과 세 가지만 남겨도 충분합니다.

로그가 있으면 다음 개선 지점이 저절로 보입니다. 대개 셋 중 하나입니다. 목표 문장이 모호해 매번 다른 해석을 하거나, 검증 기준이 너무 느슨해 잘못된 결과를 통과시키거나, 맥락이 컨텍스트 윈도우를 넘겨 앞부분을 잊는 경우입니다.

세 번째 문제는 회차가 늘어날수록 심해집니다. 매 회차의 전체 출력을 그대로 쌓지 말고 요약해서 넣는 것만으로도 상당 부분 완화됩니다.

30분 안에 하지 말아야 할 것

시간을 잡아먹는 함정은 대체로 정해져 있습니다. 아래 네 가지는 첫 에이전트에서 전부 미루시길 권합니다.

• 프레임워크부터 고르기. 어떤 라이브러리를 쓸지 비교하다 보면 30분이 그대로 사라집니다. 루프를 직접 짜 본 사람만 프레임워크가 무엇을 대신해 주는지 판단할 수 있습니다.
• 여러 도구를 한꺼번에 붙이기. 도구가 늘면 모델이 잘못 고를 여지도 늘고, 실패했을 때 어느 도구가 문제였는지 가려내기도 어려워집니다. 하나로 시작해서 안정되면 추가합니다.
• 프롬프트를 다듬는 데 시간 쓰기. 첫 실행에서 나오는 문제 대부분은 문장이 아니라 구조에서 옵니다. 검증 기준이 없으면 프롬프트를 아무리 고쳐도 결과가 안정되지 않습니다.
• 예외 처리를 미리 다 채우기. 어떤 실패가 실제로 일어나는지는 돌려 봐야 압니다. 로그를 보고 나타난 실패부터 처리하는 편이 훨씬 빠릅니다.

공통점은 전부 "실행 전에 완성도를 올리려는" 시도라는 것입니다. 첫 에이전트에서 배울 것은 대부분 첫 실행 이후에 나옵니다.

그다음은 무엇을 해야 하나?

작은 루프 하나가 안정적으로 돌면, 늘리는 방향은 두 가지입니다. 하나는 같은 구조에 도구를 하나씩 추가하는 것이고, 다른 하나는 역할을 나눠 에이전트를 여러 개 두는 것입니다.

후자로 넘어가면 역할 충돌, 검수 책임, 기록 방식 같은 새로운 문제가 생깁니다. 이 문제들을 다루는 방법은 멀티에이전트 운영법에서 정리했습니다. 에이전트에게 일을 정확히 넘기는 지시서 작성법은 작업 지시서 쓰기를 참고하시면 됩니다.

FAQ

• Q. 프레임워크를 먼저 배워야 하나요?

  • A. 아닙니다. 첫 에이전트는 반복문·조건문·함수 호출이면 충분합니다. 프레임워크는 루프를 직접 짜 본 뒤에 도입해야 무엇을 대신해 주는 것인지 이해할 수 있습니다.

• Q. 30분에 안 끝나면 잘못 하고 있는 건가요?

  • A. 대개 범위가 넓은 것이 원인입니다. 30분을 넘기고 있다면 기능을 추가하지 말고 오히려 덜어내세요. 목표를 절반으로 줄이면 대부분 다시 30분 안으로 들어옵니다.

• Q. 검증을 모델에게 맡기면 안 되나요?

  • A. 첫 에이전트에서는 권하지 않습니다. 결과를 만든 주체가 스스로 채점하면 실패를 통과시키기 쉽습니다. 파일 존재 여부나 형식 검사처럼 코드로 판정할 수 있는 것부터 시작하세요.

정리

• 30분의 관건은 코딩 속도가 아니라 범위 축소입니다. 일 하나, 도구 하나, 검증 하나로 시작합니다.
• 첫 에이전트에는 삭제·수정·외부 전송 권한을 주지 않습니다. 읽기와 새 파일 생성까지가 안전한 출발선입니다.
• 완료 조건과 중단 조건을 코드보다 먼저 적습니다. 참·거짓으로 판정되는 형태여야 합니다.
• 검증은 모델 바깥에 둡니다. 모델의 자기 보고는 검증이 아닙니다.
• 로그를 남기면 다음 개선 지점이 목표 모호성·검증 느슨함·맥락 초과 중 어디인지 바로 드러납니다.