ai agent 구현하기: “스스로 일하는” 개발 파트너 만들기

요즘 개발 현장에서 자주 듣는 말이 있습니다. “그거 에이전트로 돌리면 되지 않을까?” 단순 챗봇을 넘어, 목표를 주면 스스로 계획하고 도구를 써서 결과를 만드는 프로그램이 바로 AI Agent입니다. 이번 글에서는 “멋있어 보이니까”가 아니라, 실제로 구현 가능한 구조와 코드로 ai agent를 만들어보겠습니다.

ai agent란 무엇인가

ai agent는 크게 4가지 요소로 설명하면 이해가 빨라집니다.

• Goal(목표): 사용자가 원하는 결과(예: “에러 원인 찾아서 수정안 제시”)
• Planner(계획): 목표를 작업 단위로 쪼개는 단계
• Tools(도구): 파일 읽기/쓰기, 검색(내부), 실행, DB 조회 등
• Memory(기억): 작업 맥락, 중간 결과, 결정 이유를 저장 즉, “대화”가 중심인 챗봇과 달리, 에이전트는 행동(action)이 중심입니다.

구현 전략: 작게 만들고, 점점 키우기

처음부터 복잡한 프레임워크를 붙이면 디버깅이 어렵습니다. 저는 다음 순서로 추천합니다.

1. 단일 루프 에이전트(계획→행동→관찰→갱신)부터
2. 도구를 2~3개만 붙여서 성공 경험 확보
3. 마지막에 메모리/가드레일/재시도 정책 추가

에이전트의 기본 루프(핵심)

• Think: 지금 상황에서 뭘 해야 하지?
• Act: 도구를 호출하자
• Observe: 결과를 읽자
• Update: 다음 행동을 결정하자 이 루프를 명시적으로 코드로 박아두면 운영이 쉬워집니다.

실용 예제: “개발 작업” 도와주는 미니 에이전트

여기서는 작업 지시서(Goal)를 입력하면,

1. 할 일을 체크리스트로 만들고
2. 필요한 파일을 읽고
3. 요약/수정 제안을 만드는 형태로 구성해보겠습니다.

Python 코드: 도구 기반 ai agent 뼈대

아래 코드는 “LLM이 도구 호출을 결정한다”까지는 단순화하고, 대신 개발자가 운영 가능한 구조에 집중한 예시입니다.

from dataclasses import dataclass, field
from typing import Callable, Dict, Any, List
import json
import os

# ---- Tools ----
def read_file(path: str) -> str:
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

def write_file(path: str, content: str) -> str:
    os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
    with open(path, "w", encoding="utf-8") as f:
        f.write(content)
    return f"WROTE: {path} ({len(content)} chars)"

def make_checklist(goal: str) -> str:
    items = [
        "요구사항/제약사항 정리",
        "현재 코드/데이터 상태 확인",
        "변경 범위 산정",
        "수정안/테스트 시나리오 작성",
    ]
    return "GOAL: " + goal + "\n" + .join([  i  items])

TOOLS: [, [..., ]] = {
    : read_file,
    : write_file,
    : make_checklist,
}



 :
    goal: 
    notes: [] = field(default_factory=)
    last_observation:  = 

 :
     ():
        .tools = tools

     () -> [[, ]]:
        
        
         [
            {: , : {: state.goal}},
            
        ]

     () -> :
        tool_name = step[]
        args = step.get(, {})
         tool_name   .tools:
             
         .tools[tool_name](**args)

     () -> AgentState:
        state = AgentState(goal=goal)
        steps = .plan(state)

         step  steps:
            obs = .act(step)
            state.last_observation = obs
            state.notes.append()
            state.notes.append()

         state

 __name__ == :
    agent = SimpleAgent(TOOLS)
    result = agent.run()
    (result.last_observation)
    

이 코드가 실제로 유용한 이유

• 도구가 명확합니다: read_file, write_file처럼 개발에서 자주 쓰는 액션이 바로 연결됩니다.
• 상태가 남습니다: notes에 무슨 행동을 했고 무엇을 관찰했는지 쌓여서, 나중에 문제 재현이 쉽습니다.
• 확장이 쉽습니다: 다음 단계로 run_tests, grep, db_query 같은 도구를 추가하면 업무 자동화에 가까워집니다.

사례: “버그 트리아지” 에이전트로 확장하기

실무에서 자주 먹히는 패턴은 다음입니다.

1. 사용자가 “에러 로그”를 붙여넣는다
2. 에이전트가 재현 조건/의심 지점/확인할 파일 목록을 만든다
3. 저장소에서 관련 파일을 읽어 요약한다
4. 변경 제안 + 테스트 시나리오를 문서로 남긴다 여기서 핵심은 도구 호출의 안전장치입니다. 예를 들어 파일 쓰기는 “초안 생성”까지만 허용하고, 실제 커밋은 사람이 하게 하는 식으로요.

구현할 때 자주 막히는 포인트 3가지

1) 도구 입력 형식이 제각각이라 관리가 어렵다

도구는 가능하면 함수 시그니처를 단순하게 유지하세요. str -> str 형태가 시작하기 좋습니다.

2) 에이전트가 쓸데없이 장황해진다

출력 형식을 강제하면 개선됩니다. 예:

• “요약 5줄 + 액션 아이템 5개 + 리스크 3개”처럼 템플릿을 둡니다.

3) 한 번 실패하면 끝난다

재시도 정책을 넣으세요.

• 도구 호출 실패 시 1~2회 재시도
• 그래도 실패하면 “대안 플랜”으로 전환(예: 파일 읽기 실패 → 사용자에게 경로 확인 질문)

마무리: ai agent는 “구조”가 반이다

ai agent 구현은 거창한 마법이라기보다, 목표-계획-도구-기억을 개발 친화적으로 엮는 작업입니다. 오늘 소개한 뼈대만 잡아도 “체크리스트 생성”, “코드 요약”, “수정안 초안 작성” 같은 개발 업무가 빠르게 자동화됩니다.

원하시면 다음 단계로,

• 여러 도구를 선택하도록 간단한 라우터 붙이기
• 작업 기록을 파일로 남기는 메모리 저장소 추가
• “민감 파일 접근 금지” 같은 가드레일 설계 까지 이어서 정리해드릴게요.