첫 AI 에이전트 만들기: 모델, 몇 개의 도구, 그리고 루프

"AI 에이전트"라고 하면 프레임워크와 벡터 데이터베이스, 그리고 주말 내내 걸리는 셋업이 필요할 것처럼 들린다. 그렇지 않다. Anthropic 자체의 정의는 산뜻할 정도로 작다. 에이전트란 LLM이 루프 안에서 자율적으로 도구를 사용하는 것이다. 이 패턴이 한번 눈에 들어오면, 100줄도 채 안 되는 코드로 쓸 만한 첫 에이전트를 만들 수 있다. 그리고 그에 못지않게 중요한 것은, 언제 만들지 말아야 하는지도 알게 된다는 점이다.

핵심 루프

아무리 화려한 에이전트라도, 모두 똑같은 네 단계 주기다.

1. 모델에게 목표와, 호출이 허용된 도구 목록을 준다.
2. 모델은 직접 답할지, 아니면 도구를 호출할지 결정한다.
3. 당신의 코드가 도구를 실행하고 그 결과를 다시 모델에게 전달한다.
4. 모델이 끝났다고 말할 때까지 반복한다.

모델은 결코 당신의 파일시스템이나 네트워크를 직접 건드리지 않는다. 모델은 오직 도구를 실행해 달라고 요청할 뿐이며, 실제로 실행할지 그리고 어떻게 실행할지는 당신의 코드가 결정한다. 바로 그 틈새에 당신의 모든 안전장치가 자리한다.

구체적인 예제

다음은 계산기 도구를 사용해 질문에 답할 수 있는 최소한의 에이전트다. 중요한 것은 그 구조다. 동일한 형태가 파일 편집, 웹 검색, 데이터베이스 질의로 확장된다.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

저 while 루프가 바로 에이전트다. 모델은 질문을 보고, "1894 * 37 + 12"로 calculator를 호출하기를 요청하고, 당신의 코드가 그것을 실행해 70090을 돌려주면, 모델이 최종 답을 작성한다. 계산기를 read_file/write_file 한 쌍으로 바꾸면 원시적인 코딩 에이전트가 된다.

정말로 중요한 부분은 도구다

모델은 당신이 부여한 도구만큼만 유능하며, 대부분의 첫 에이전트가 실패하는 지점은 도구 설계다. 에이전트용 도구 작성에 관한 Anthropic의 지침은 몇 가지 규칙으로 요약된다.

• 새 동료에게 설명하듯 도구의 이름을 짓고 설명하라. search_invoices(customer_id, date_range)가 모호한 query(sql)보다 낫다. 계약이 명확할수록 잘못된 호출이 줄어든다.
• 원시 덤프가 아니라 신호가 높은 결과를 반환하라. 도구가 JSON 5,000줄을 반환한다면, 당신은 방금 모델의 컨텍스트 예산을 노이즈에 써 버린 것이다. 유용한 것으로 잘라내라.
• 오류를 교훈적으로 만들어라. "File not found: did you mean config.yaml?"는 모델이 회복하도록 돕지만, 맨 스택 트레이스는 대개 그러지 못한다.

실행시키기 전에 가드레일을

당신의 코드가 모든 도구 호출을 실행하므로, 안전은 당신의 책임이다. 에이전트가 실제 무언가를 건드리기 전에 추가할 세 가지 가드레일이다.

• 루프에 상한을 둬라. 최대 반복 횟수를 추가해, 혼란에 빠진 에이전트가 영원히 돌면서 (요금을 쌓아 올리지) 못하게 하라.
• 파괴적 동작에 관문을 둬라. 삭제하거나, 전송하거나, 결제하는 모든 것은 확인을 거치거나 먼저 샌드박스에서 실행되어야 한다.
• 도구 입력을 검증하라. 신뢰할 수 없는 문자열을 절대 eval()하거나 모델 출력을 셸에 바로 넘기지 마라. 모든 도구 인자를 신뢰할 수 없는 사용자 입력으로 취급하라. 사실상 그렇기 때문이다.

에이전트를 만들지 말아야 할 때

일찍 배워 두면 가장 유용한 것은, 많은 문제가 애초에 에이전트를 전혀 필요로 하지 않는다는 사실이다. 단계가 미리 정해져 있다면 — 데이터를 가져오고, 요약하고, 그 요약을 이메일로 보내는 것 — 한두 번의 모델 호출이 들어간 평범한 스크립트가 더 저렴하고, 더 빠르며, 디버깅하기도 쉽다. Anthropic은 이를 워크플로라고 부르며, 경로가 예측 가능할 때는 언제나 이를 권장한다. 모델이 찾아낸 것을 바탕으로 다음에 무엇을 할지 진정으로 결정해야 할 때에만 진짜 에이전트로 손을 뻗어라.

위의 네 단계 루프에서 시작해, 잘 설명된 도구 한두 개를 주고, 반복 횟수에 상한을 두고, 실제 작업을 부여하라. 어떤 분량의 프레임워크 문서보다도, 작동하는 에이전트 하나에서 더 많이 배우게 될 것이다.