그래서 저는 그것들을 처음부터 다시 만들었습니다. 의존성(dependencies)이 없는 아주 작은 프레임워크로, 한 번에 읽고 진정으로 이해할 수 있을 만큼 작게 만들었습니다.

갈증 (The itch)

저는 LangGraph나 OpenAI Agents SDK와 같은 에이전트 프레임워크를 사용합니다. 그것들은 훌륭합니다. 하지만 학습할 때는 마치 마법처럼 느껴질 수 있습니다. 몇 가지 요소를 서로 연결하면 에이전트가 나타나는데, 그 중간 과정에서 정확히 어떤 일이 일어났는지 확신할 수 없습니다.

저는 더 많은 마법을 원하지 않았습니다. 저는 기계의 내부를 보고 싶었습니다.

그래서 저는 신경망(neural networks)을 다룰 때 저에게 매우 효과적이었던 방식을 사용했습니다. 만약 Andrej Karpathy가 micrograd를 구축하는 것을 보셨다면, 그 느낌을 아실 겁니다. 그는 PyTorch의 핵심 아이디어를 약 150줄 정도로 다시 만들었습니다. PyTorch를 대체하기 위해서가 아니라, 오해하는 것이 불가능하도록 만들기 위해서였습니다. 그 이후로 PyTorch는 더 이상 마법이 아니게 됩니다.

저는 에이전트에 대해서도 똑같은 것을 원했습니다. 그래서 microagent를 만들었습니다.

요령: 작은 사무실을 상상해 보세요

에이전트를 이해하는 가장 빠른 방법은 작은 사무실을 상상하는 것입니다.

새로운 비서가 첫 출근을 합니다. 그들에게는 노트 한 권, 도움을 요청할 수 있는 몇 명의 동료, 그리고 한 가지 단순한 습관이 있습니다. 일이 끝날 때까지 계속 일하는 것입니다.

그것이 아이디어의 전부입니다. 아래의 모든 것은 단지 코드로 작성된 그 사무실일 뿐입니다. 이는 다섯 가지 작은 조각으로 요약됩니다.

1. 메시지 (Message), 단 하나의 메모

사무실에서 가장 작은 단위는 메모 하나입니다. 누군가 질문을 합니다. 비서는 결정을 적습니다. 동료가 답변을 건넵니다. 이 각각이 하나의 메모입니다.

@dataclass(frozen=True)
class Message:
    role: str            # "user", "assistant", or "tool"
...

이것은 'frozen' 상태인데, 이는 펜으로 썼다는 뜻의 멋진 표현입니다. 일단 메모가 존재하면 절대 변하지 않습니다. 이는 잠시 후에 중요해집니다.

2. 컨텍스트 (Context), 노트

노트 하나만으로는 쓸모가 없습니다. 어시스턴트(Assistant)에게는 전체 실행 이력이 필요합니다. 그 이력이 바로 컨텍스트 (Context)입니다. 이를 사무실의 업무 수첩이라고 생각하세요.

모든 것을 단순하게 만드는 단 하나의 규칙이 있습니다. 페이지를 절대 지우지 않는 것입니다. 오직 끝에 새로운 노트를 추가할 뿐입니다.

@dataclass(frozen=True)
class Context:
    messages: tuple = ()
...

수첩은 계속해서 커지기만 하므로, 발생한 일에 대한 전체 이야기가 항상 그곳에 있습니다. 이를 다시 읽고, 재생하고, 디버깅 (Debug)할 수 있습니다. 아무것도 숨겨지지 않습니다. 메모리 (Memory)는 나중에 추가하는 기능이 아닙니다. 그것은 우리가 절대 지우지 않는 수첩일 뿐입니다.

3. 툴 (Tool), 당신이 부를 수 있는 동료

어시스턴트는 혼자서 모든 것을 할 수 없습니다. 숫자를 계산해야 하나요? 계산기를 가진 사람을 부르세요. 파일을 가져와야 하나요? 파일 캐비닛을 아는 사람을 부르세요.

툴 (Tool)은 정확히 그것입니다. 당신이 요청을 건네면, 그것이 결과를 돌려줍니다.

@dataclass
class Tool:
    name: str
...

한 가지 특별한 툴이 있습니다. 우리의 작업이 끝났으며, 정답은 X라고 말하는 것이 직업인 동료입니다. 우리는 그것을 터미널 (Terminal)로 표시합니다.

4. 정책 (Policy), 두뇌

이제 흥미로운 부분입니다. 다음에 무엇을 할지 누가 결정할까요? 수첩을 보고 다음 동작을 선택합니다. 그 결정권자가 바로 정책 (Policy)입니다. 그것이 두뇌입니다.

결정에는 두 가지 부분이 있습니다. 어떤 툴을 호출할 것인지, 그리고 그것을 어떤 인자 (Arguments)와 함께 호출할 것인지입니다.

@dataclass(frozen=True)
class Action:
    tool: str
...

이 프로젝트 전체에서 가장 중요한 아이디어입니다. 두뇌는 교체 가능합니다 (Swappable). 오늘은 사무실이 돌아가는 것을 관찰하기 위해 AI를 전혀 사용하지 않고 몇 줄의 일반적인 Python 코드로 작성할 수 있습니다. 내일은 실제 언어 모델 (Language Model)이나, 당신이 직접 훈련시킨 작은 신경망 (Neural Network)으로 교체할 수 있습니다. 사무실은 변하지 않습니다. 오직 두뇌만 변할 뿐입니다.

두뇌를 교체하되, 몸체는 유지하세요.

5. 에이전트 (Agent), 계속해서 일하는 어시스턴트

마지막으로 이 모든 것을 하나로 묶습니다. 에이전트 (Agent)는 두뇌를 보유하고, 동료들을 알며, 하나의 습관을 루프 (Loop) 안에서 따릅니다.

class Agent:
    def __init__(self, brain, tools, max_steps=6):
        self.brain = brain
...

그 루프가 여러분이 들어본 모든 AI 에이전트의 전체 엔진입니다. 결정하고, 행동하고, 기록하고, 반복합니다. 거대한 프레임워크들은 이를 화려하게 꾸며 놓았지만, 그 밑바닥에 있는 본질은 바로 이것입니다.

실제 작업을 수행하는 모습 보기

여기 환불을 처리하는 고객 지원 에이전트가 있습니다. 주문 내역을 조회하고, 정책을 확인하며, 사람이 승인한 후 환불을 실행하고, 고객에게 답장을 보냅니다. 실제 도구들을 향해 겨냥된 동일한 다섯 가지 요소일 뿐입니다.

질문: "주문 A1234에 대해 환불받을 수 있을까요? 파손된 상태로 도착했습니다."
  지원 에이전트의 생각: 먼저 주문 내역을 불러오겠습니다.
    -> look_up_order 결과: A1234, 무선 헤드폰, $79, 배송 완료, 결함 보고됨
...

세 번째 단계를 주목하세요. 위험한 작업은 사람이 승인할 때까지 기다렸습니다. 이것은 특별한 기능이 아닙니다. 다른 도구를 감싸는(wrap) 하나의 도구일 뿐입니다.

어려운 부분들은 새로운 조각이 아닙니다

이 부분이 제가 예상하지 못했던 부분이며, 작게 만들어야 하는 가장 좋은 이유입니다.

어렵고 실제적인 기능을 추가하려고 할 때, 그중 어떤 것도 새로운 빌딩 블록 (building block)을 필요로 하지 않습니다.

• 멀티 에이전트 (Multi-agent)는 그저 동료로서 사용되는 에이전트일 뿐입니다. 에이전트는 다른 에이전트에게 도구로서 전달될 수 있습니다. 그것이 멀티 에이전트 시스템의 전부입니다.
• 안전성 (Safety)은 그저 문지기가 있는 동료입니다. 위험한 도구를 먼저 승인을 요청하는 도구로 감싸면 됩니다.
• 폭발하지 않는 메모리 (Memory)는 하나의 함수입니다. 긴 노트를 입력하면, 더 짧게 요약된 노트가 출력됩니다.
• 오류로부터의 복구 (Recovering from errors)는 대부분 공짜나 다름없습니다. 오류를 노트에 기록하면, 브레인 (brain)은 다음 턴에 자신의 실수를 확인하고 이를 수정합니다.

이 모든 것들은 동일한 다섯 가지 요소를 조금씩 다르게 배치한 것뿐입니다. 어려운 문제들이 새로운 근본 원리를 요구하지 않는다면, 그것은 이 다섯 가지 요소가 올바른 구성 요소라는 강력한 신호입니다.

솔직한 부분

솔직한 부분

microagent는 프로덕션용 프레임워크(production framework)가 아니며, 그렇게 되려고 노력하지도 않습니다. 만약 실제로 제품을 출시해야 한다면, LangGraph나 OpenAI Agents SDK를 사용하세요. 그것들은 매우 훌륭하며, 교육용 프로젝트가 흉내 내지 말아야 할 복잡한 현실 세계의 문제들을 해결해 줍니다.

microagent의 목적은 완전히 다릅니다. 모든 줄을 읽고, 모든 조각을 이해한 다음, 그 밑바닥에 무엇이 있는지 정확히 아는 상태에서 진짜 결과물을 만들어 가십시오.

직접 해보기

저장소(repo)는 여기 있습니다: github.com/rahul1368/microagent.

가장 좋은 접근 방식은 처음부터 시작하는 노트북(from-scratch notebook)을 사용하는 것입니다. 이 노트북은 사무실 이야기와 함께 다섯 가지 요소를 하나씩 재구축하며, 매 단계마다 실행됩니다. 그 과정을 거치고 나면, 코드가 이미 알고 있는 것처럼 느껴질 것입니다. 왜냐하면 당신이 직접 작성했을 것이기 때문입니다.

이 글이 도움이 되었다면, 저장소에 별(star)을 남겨주시는 것이 큰 힘이 됩니다. 또한, 어떤 부분이 당신에게 에이전트(agents)의 원리를 깨닫게 해주었는지 꼭 듣고 싶습니다.