커스텀 에이전트 작성하기

커스텀 에이전트 작성하기 (Custom Agents)

AutoGen의 AssistantAgent는 좋은 기본값을 제공하지만, 곧 "내 앱에 딱 맞는 에이전트를 만들고 싶다"는 요구가 생겨요. AutoGen을 사용하면 자신만의 커스텀 에이전트를 작성할 수 있어요. 핵심은 다음 두 가지 개념이에요.

출처: Custom Agents — AutoGen 공식 문서

일반적으로 에이전트의 행동을 정의하는 함수형(configuration) 측면: AssistantAgent의 model_client, tools, system_message 등.
구조적으로 에이전트를 정의하는 측면: 에이전트 타입(agent type)과 동작 방식.

언제 커스텀 에이전트가 필요한가?

일반적인 AssistantAgent로 대부분의 작업을 처리할 수 있어요. 커스텀 에이전트가 필요해지는 상황은 보통 에이전트 내부의 "제어 흐름"을 바꿔야 할 때예요. 예를 들어 모델 호출 사이에 처리 단계(예: 이미지 캡처, 코드 실행, 추가 검증)를 끼워 넣고 싶다면 AssistantAgent를 상속받아 메시지 처리 동작을 재정의하면 돼요.

BaseAgent와 AssistantAgent 상속하기

커스텀 에이전트를 만드는 두 가지 경로가 있어요.

BaseAgent를 상속하는 경우, 메시지가 도착할 때마다 호출되는 on_messages 메서드를 직접 구현해야 해요. 모든 메시지 처리 로직을 스스로 작성해야 하므로 가장 유연하지만 가장 많은 작업이 필요해요.

AssistantAgent를 상속하는 경우, 모델 클라이언트나 툴 관리 같은 기본 기능을 상속받으면서 특정 동작만 재정의할 수 있어요. 이 경로는 훨씬 간단하고, 대부분의 커스텀 시나리오에 충분해요.

예제: 도구 호출 전에 상태를 업데이트하는 에이전트

AssistantAgent를 상속받아, 에이전트가 활동할 때마다 내부 상태를 기록하는 커스텀 에이전트를 만들어 볼게요.

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.base import Response
from autogen_agentchat.messages import AgentMessage, ChatMessage
from typing import Sequence
from autogen_core import CancellationToken
from autogen_ext.models.openai import OpenAIChatCompletionClient

class EnhancedAssistantAgent(AssistantAgent):
    def __init__(self, name: str, model_client: OpenAIChatCompletionClient | None = None, **kwargs) -> None:
        super().__init__(name=name, model_client=model_client, **kwargs)
        self._steps_count: int = 0

    async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:
        # 에이전트가 활동할 때마다 상태만 갱신
        self._steps_count += 1
        # 나머지는 부모 클래스가 처리
        return await super().on_messages(messages, cancellation_token)

이렇게 하면 에이전트가 활동한 횟수를 추적하면서도, 모델 호출·툴 실행 등 AssistantAgent의 기존 동작은 전부 그대로 유지할 수 있어요.

핵심 포인트는, 커스텀 에이전트는 상속으로 시작한다는 거예요. BaseAgent 전체를 처음부터 구현하는 것보다 AssistantAgent에 필요한 동작만 골라 덮어쓰는 방식이 훨씬 실용적이에요. 프로덕션에서 복잡한 제어 흐름이 필요할 때 이 패턴이 큰 힘을 발휘해요.

커스텀 에이전트 작성하기