박명수 만들기

📌 우리는 왜 박명수를 만들어야 할까?

심심할 때 박명수가 나와 대화를 해 주면 참 좋겠는데, 박명수에게 친구비를 주기엔 주머니 사정이 넉넉하지 않다….

하지만 우리에겐 코딩을 할 수 있는 맥북과 코딩 천재 지피티가 있으니, 가짜 박명수를 만들어 자급자족하면 된다 😈

📌 Embabel에 대해 알아보자

Embabel은단순히텍스트를생성하는것을넘어사용자를대신해추론하고목표지향적으로행동하며계획을세우고도구를호출하는지능형에이전트를구축하기위한JVM기반의에이전트프레임워크로개발자가복잡한워크플로우를일일이코딩하지않아도에이전트가스스로목표를달성하기위한최적의액션순서를결정하도록돕는다.(아이고 숨차)

세 줄 요약을 더 요약하자면, 대충 AI 에이전트 개발을 위해 사용하는 프레임워크이다.

 

⚡️ 1. GOAP(Goal-Oriented Action Planning)

GOAP라는 비-LLM 알고리즘을 사용해서 목표 달성을 위한 최적의 경로를 스스로 찾는 것이 특징이다. 백준 실버 3 이상부터만 사용할 수 있는 프레임워크이다.

 

이해를 돕기 위해 설명을 추가하자면,

원래 우리는 어떤 비즈니스 로직의 실행을 위해 다음과 같이 코드를 작성한다:

1. 사과를 씻어서 준비한다.
2. 바나나를 씻어서 준비한다.
3. 꼬치를 준비한다.
4. 꼬치에 사과와 바나나를 꽂는다.
5. 설탕을 녹인다.
6. 녹은 설탕을 꼬치에 짜잔 해서 탕후루를 타란 ✨

 

그런데 이 프레임워크를 사용하게 되면 코드를 이렇게 짜게 된다:

최종 목표: 탕후루 타란 ✨
허용된 행동 목록
- 사과 씻어서 준비하기 (준비물: 없음, 결과물: 뽀득뽀득 사과)
- 바나나 씻어서 준비하기 (준비물: 없음, 결과물: 뽀득뽀득 바나나)
- 꼬치 준비하기 (준비물: 없음, 결과물: 그냥 꼬치)
- 꼬치에 사과랑 바나나 꽂기 (준비물: 뽀득뽀득 사과, 뽀득뽀득 바나나, 그냥 꼬치, 결과물: 최강 꼬치)
- 설탕 녹여서 설탕물 만들기 (준비물: 없음, 결과물: 설탕물)
- 최강 꼬치에 설탕물을 짜잔 해서 탕후루를 타란 ✨ (준비물: 최강 꼬치, 설탕물, 결과물: 타란 탕후루)

 

위상 정렬의 냄새가 솔솔… (하지만 GOAP는 더 복잡한 경로 탐색을 위해 단순한 순서 정렬을 넘어, 행동의 비용과 성공 확률까지 계산해 최적의 경로를 찾는다)

이렇게 작성을 하면 embabel이 GOAP 알고리즘을 사용해, 알아서 어떤 행동을 실행할지, 그리고 그 행동들을 어떤 순서로 실행해서 최종 목표인 탕후루 타란을 도출할지 경로를 스스로 찾는 구조이다. 이 경로 추론의 핵심이 되는 것은 각 행동의 입력과 출력 타입이다, 위 예시에서 본다면 '꼬치에 사과랑 바나나 꽂기' 라는 행동에는 뽀득뽀득 사과, 뽀득뽀득 바나나, 그냥 꼬치가 필요하니 이 준비물들을 만들어 주는 행동을 먼저 수행하도록 순서를 정하는 식이다 👀

 

(잠깐 쿠키런 오븐브레이크 영입하자면, 이 게임에는 짱귀여운 감귤탕후루맛쿠키가 있습니다 🍊🍊 쿠오븐 유저는 삐삐 쳐주세요 친구코드 들고 날아갈게요 🤸‍♂️)

 

 

그런데 솔직히 코드를 짜는 입장에서는 전자의 방식이 훨씬 직관적이고 흐름도 파악하기 쉽고, 굳이 이 GOAP 알고리즘을 도입해 프레임워크에서 코드의 실행을 제어하는 것이 무슨 장점이 있다는 건지 처음에는 납득이 안 됐다 😒

 

그러다 알게 된 사실은, 자동 계획(GOAP)의 진가는 예외 상황에서 나타난다는 것이다.

 

만약에 우리가 어느 날 갑자기 뚱이가 되어 버렸다고 가정해 보자:

 

아무래도 한 손에 손가락이 다섯 개에서 0개로 바뀐다면 꼬치에 사과나 바나나를 꽂다가 바닥에 떨어트리는 일이 자주 생길 것이다. 그러면 이런 킹받는 코드가 탄생한다:

public Tanghulu makeTanghulu() {

    Apple apple = null;
    Banana banana = null;
    Skewer skewer = null;
    SkewerWithFruit fruitSkewer = null;
    SugarWater sugarWater = null;

    // 사과 준비
    while (apple == null) {
        try {
            apple = washApple();
        } catch (AppleDroppedException e) {
            System.out.println("사과 떨어짐! 다시 씻는다.");
        }
    }

    // 바나나 준비
    while (banana == null) {
        try {
            banana = washBanana();
        } catch (BananaDroppedException e) {
            System.out.println("바나나 떨어짐! 다시 씻는다.");
        }
    }

    // 꼬치 준비
    skewer = prepareSkewer();

    // 과일 꽂기 (여기서 떨어질 수 있음)
    while (fruitSkewer == null) {
        try {
            fruitSkewer = stickFruit(skewer, apple, banana);
        } catch (FruitDroppedException e) {

            System.out.println("과일 떨어짐! 다시 준비");

            // 떨어진 과일 다시 준비
            apple = null;
            banana = null;

            while (apple == null) {
                try {
                    apple = washApple();
                } catch (AppleDroppedException ignore) {}
            }

            while (banana == null) {
                try {
                    banana = washBanana();
                } catch (BananaDroppedException ignore) {}
            }
        }
    }

    // 설탕 녹이기
    sugarWater = meltSugar();

    // 최종 탕후루
    return coatSugar(fruitSkewer, sugarWater);
}

 

핵심 문제는 절차형 코드에서는 상태 복구 로직이 복잡해지는 것이다. 그리고 끔찍하게도 설탕이 타거나, 꼬치가 부러지거나, 바나나 껍질을 깠더니 썩은 바나나가 나온 것과 같은 다양한 실패 케이스들은 아직 코드에 적용하지도 않은 상태이다.

 

무엇보다 우리가 할 에이전트 개발의 핵심이 되는 AI는… 해마 이모지를 보여 달라고 하면 고장나는 치명적인 버그가 있다 🤦‍♀️🤦‍♀️

 

개복치 ChatGPT 하나만 봐도 알 수 있듯, 에이전트 개발에 있어 회복 탄력성을 핸들링하는 것은 매우 중요하다.

🤔 2. Embabel의 회복 탄력성은 어디에서 오는가

Embabel에는 에이전트 프로세스가 실행되는 동안 상태를 유지하고 데이터를 공유하는 블랙보드라는 중앙 저장소 같은 공간이 있다. 준비가 완료된 뽀득뽀득 사과랑 뽀득뽀득 바나나를 저장해 놓고 있는 보관함 정도로 생각하면 된다! 바나나가 썩었거나 꼬치를 떨어트리면, 이 보관함에서 준비물이 부족해진 것을 Embabel이 GOAP를 통해 파악할 수 있는 구조인 것이다.

 

Embabel은 블랙보드와 GOAP를 결합하여 아래와 같이  루프를 형성한다:

1. Observe (관찰): 현재 블랙보드의 상태와 이전 액션의 결과를 확인한다.
2. Orient (방향 설정): 마지막 계획 수립 이후 무엇이 변했는지 파악한다.
3. Decide (결정): GOAP 플래너가 새로운 정보를 바탕으로 계획을 수립하거나 업데이트한다.
4. Act (실행): 계획된 다음 액션을 실행하고 결과를 블랙보드에 반영한다.

🚨 "예외 상황에서 진가가 나타난다"는 문장에 오해의 소지가 있을 것 같아 덧붙이자면, 실제로 Embabel은 에러가 났을 때만 다시 계획을 세우는 것이 아니라 매 행동이 끝날 때마다 루프를 돌며 상태를 재평가한다.

 

📌 Embabel 기초 쌓기

embabel을 활용해 프로젝트를 만들어 보고 싶은 경우에는 아래 예시 repository를 clone하면 된다:

https://github.com/embabel/embabel-agent-examples

GitHub - embabel/embabel-agent-examples: Agent Framework Examples for Java and Kotlin Developers

 

아래는 Embabel 문서에 있는 Agent 클래스의 예시 코드이다.

@Agent(description = "Find news based on a person's star sign")  
public class StarNewsFinder {

    private final HoroscopeService horoscopeService;  
    private final int storyCount;

    public StarNewsFinder(
            HoroscopeService horoscopeService,  
            @Value("${star-news-finder.story.count:5}") int storyCount) {
        this.horoscopeService = horoscopeService;
        this.storyCount = storyCount;
    }

    @Action  
    public StarPerson extractStarPerson(UserInput userInput, OperationContext context) {  
        return context.ai()
            .withLlm(OpenAiModels.GPT_41)
            .createObject("""
                Create a person from this user input, extracting their name and star sign:
                %s""".formatted(userInput.getContent()), StarPerson.class);  
    }

    @Action  
    public Horoscope retrieveHoroscope(StarPerson starPerson) {  
        // Uses regular injected Spring service - not LLM
        return new Horoscope(horoscopeService.dailyHoroscope(starPerson.sign()));  
    }

    @Action  
    public RelevantNewsStories findNewsStories(
            StarPerson person, Horoscope horoscope, OperationContext context) {  
        var prompt = """
            %s is an astrology believer with the sign %s.
            Their horoscope for today is: %s
            Given this, use web tools to find %d relevant news stories.
            """.formatted(person.name(), person.sign(), horoscope.summary(), storyCount);

        return context.ai().withDefaultLlm()
            .withToolGroup(CoreToolGroups.WEB)  
            .createObject(prompt, RelevantNewsStories.class);
    }

    @AchievesGoal(description = "Write an amusing writeup based on horoscope and news")  
    @Action
    public Writeup writeup(
            StarPerson person, RelevantNewsStories stories, Horoscope horoscope,
            OperationContext context) {  
        var llm = LlmOptions.fromCriteria(ModelSelectionCriteria.getAuto())
            .withTemperature(0.9);  

        var storiesFormatted = stories.items().stream()
            .map(s -> "- " + s.url() + ": " + s.summary())
            .collect(Collectors.joining("\n"));

        var prompt = """
            Write something amusing for %s based on their horoscope and news stories.
            Format as Markdown with links.
            <horoscope>%s</horoscope>
            <news_stories>
            %s
            </news_stories>
            """.formatted(person.name(), horoscope.summary(), storiesFormatted);  

        return context.ai().withLlm(llm).createObject(prompt, Writeup.class);  
    }
}

 

@Agent

Agent는 특정 목표를 달성하기 위해 도메인 로직, AI 역량, 도구 사용을 하나로 묶은 독립적인 구성 요소를 정의할 때 사용된다. 클래스 레벨에 이 어노테이션이 붙은 경우, 해당 클래스가 multi-step flow를 수행할 수 있는 에이전트임을 프레임워크에 알리는 역할을 한다. @Agent 작성 시 description 파라미터는 필수로 제공되어야 하는데, 이는 사람이 읽기 위한 용도일 뿐만 아니라, LLM이 사용자의 입력에 가장 적합한 에이전트를 선택하거나 순위를 매길 때 중요한 기준으로 사용된다.

 

+) Spring Component 어노테이션을 포함하고 있어서 알아서 빈으로 등록된다

@Action

에이전트 내부에 여러 public 메서드에 @Action 이 붙어 있는 것을 확인할 수 있다. 이게 앞서 예시에서 언급한 행동 목록들이다. @Action은 에이전트가 목표를 달성하기 위해 취할 수 있는 개별적인 단계 또는 기능을 정의하는 역할을 한다. 이 액션 메서드의 파라미터와 반환값은 프레임워크가 실행 계획을 세우는 핵심 지표가 된다. 

설정할 수 있는 파라미터가 굉장히 다양한데 야무지게 써먹으면 더 멋진 에이전트가 만들어질지도…?

 

Non-LLM Action

    @Action  
    public Horoscope retrieveHoroscope(StarPerson starPerson) {  
        // Uses regular injected Spring service - not LLM
        return new Horoscope(horoscopeService.dailyHoroscope(starPerson.sign()));  
    }

retrieveHoroscope 메서드를 읽어보면 알 수 있듯, 모든 Action에 ai에 대한 호출이 있어야 하는 것은 아니다. 이런 식으로 전통적인 방식의 개발 방식과 ai를 이용한 개발을 적절하게 잘 조합할 수 있다는 것을 나름의 장점으로 꼽을 수 있다 👀 

Multi-Input 의존성

    @Action  
    public RelevantNewsStories findNewsStories(
            StarPerson person, Horoscope horoscope, OperationContext context) {  }

    @AchievesGoal(description = "Write an amusing writeup based on horoscope and news")  
    @Action
    public Writeup writeup(
            StarPerson person, RelevantNewsStories stories, Horoscope horoscope,
            OperationContext context) { }

findNewsStories 메서드를 보면 StarPerson과 Horoscope를 입력으로 받는데 input이 몇 개가 되든 가능한 실행 경로가 있다면 Embabel이 정교하게 오케스트레이션을 해 준다. 입력 복잡도 최고봉은 writeup메서드이다, 블랙보드 + GOAP를 지닌 Embabel은 무적이애 🫨

 

따뜻한 아이스 아메리카노 한 잔 주세요

놀랍게도 그런 주문이 Embabel에서는 정말로 가능하다느뇽….

	var llm = LlmOptions.fromCriteria(ModelSelectionCriteria.getAuto())
            .withTemperature(0.9);

 

 

withTemperature로 ai 응답에 대한 옵션을 줄 수 있는데, 온도가 높을수록 조금 더 창의적인 답변을 준다고 한다.

아래 둘 중 하나는 온도를 0.1로 설정한 거고 하나는 1.0으로 설정하고 동일한 질문을 한 것이다. 

어느 쪽이 1.0을 입력한 건지는…알아서 맞혀 보세요

 

+) 번외, AI는 따뜻해도 차갑다

1+1을 물어봤을 때 당연히 창의적인 쪽은 귀요미라고 대답해 줄 것을 기대했는데… 둘이 똑같이 대답해서 굉장히 실망스러웠다 (내 토큰 돌려줘) 인간이 생각하는 것보다는 덜 창의적인 것 같다.

 

@AchievesGoal

이건 Agent의 최종 목표를 정의하는 핵심 어노테이션으로, 요녀석이 붙은 메서드는 해당 에이전트가 달성해야 할 목적지에 도달했음을 프레임워크에게 알리는 역할을 한다.

혹시나 개발하다 목표 지정을 빼먹을까봐 걱정하지 않아도 된다. 왜냐하면

안 넣으면 Embabel이 열심히 화내준다 🔥

네가 도구까지 사용하면 내 밥그릇은…

슬프게도 망치를 쥐여줘도 머리만 긁적거리는 원숭이들과 다르게, AI에게는 망치라는 도구를 주고 그 용도를 알려주면 뚝딱뚝딱 집을 짓는다.

그러니 지금부터 미리미리 기강을 잡아두도록 하자 :)

        return context.ai().withDefaultLlm()
            .withToolGroup(CoreToolGroups.WEB)  
            .createObject(prompt, RelevantNewsStories.class);

아무튼 코드 내에서는 이런 식으로 사용할 도구를 직접 지정해 줄 수도 있다.

 

UserInput

Embabel에서는 UserInput 클래스를 다음과 같이 설명한다.

UserInput은 프레임워크가 이 데이터는 사용자로부터 온 처리되지 않은 원시 입력이라는 것을 인식하게 하는 핵심 타입이다.

 

💩 작은 고민 포인트: 이미 Request DTO가 있는데 굳이 UserInput 타입으로 넘겨줘야 할까?

사실 코드를 작성하는 당시에는 별생각 없이 예시에 있던 Agent와 동일하게 UserInput을 넣어주는 식으로 구현을 했는데, Shell 모드로 구동하는 Agent인 경우에는 사용자의 입력이 고정된 텍스트이고 어떤 Agent가 필요할지 LLM이 직접 개입하여 판단하는 과정이 필요했기 때문에 UserInput으로 넣는 것이 정석이었지만,  웹으로 구현한 서비스에 Agent를 붙일 때는 Input의 규격이 딱 정해져 있어서 굳이 UserInput을 넘겨줘야 하나? 하는 의문이 들었다.

 

UserInput은 UserContent를 상속하기 때문에 프레임워크가 가드레일을 적용할 때, 사용자로부터 온 입력에 대해서만 유해성 검사를 수행하도록 트리거하는 기준이 된다. 그러니까 UserInput으로 넣어주면 개발자가 가공을 통해 넣은 값이 아닌 순수 외부 사용자의 입력임을 명시하고 검증이나 정제를 거치도록 유도할 수 있는 것이다.

 

 

그러나 별다른 처리가 필요한 것이 아니라면 AgentInvocation.invoke(myRequestDto)와 같은 식으로 dto를 직접 입력해도 문제가 되는 것은 아니다. 다만, 추측을 해 보자면 Shell모드의 경우 일반적으로 UserInput이 진입점이 되기 때문에 처음부터 UserInput을 받도록 에이전트를 개발하면 Shell과 웹 애플리케이션에 모두 호환되어 재사용이 가능하다는 장점이 있을 것 같다.

구분	UserInput	requestDto 직접 입력
입력 형태	자유로운 텍스트, 설명, 메시지	필드가 정해진 폼 데이터, API 요청
에이전트 역할	텍스트 분석 및 정보 추출 (DICE)	추출된 정보를 바탕으로 업무 수행
주요 장점	OODA 루프의 첫 단계를 유연하게 시작	불필요한 LLM 추론 비용 절감 및 정확도 향상
보안	UserContent 기반 가드레일 작동	내부 비즈니스 로직으로 직접 주입

 

요약하자면 이미 데이터가 구조화되어 있다면 직접 넘겨도 되지만, 사용자가 입력한 자연어를 분석하여 특정 도메인 객체를 추출해야 하는 상황이라면 UserInput으로 감싸서 호출하는 것이 Embabel의 타입 안전성과 자동 오케스트레이션 기능을 가장 잘 활용하는 방법이다. 개발에는 정말 정답이 없어요 🥲

 

📌  초초초간단 애플리케이션 만들어 보기

우리가 만들 것은 바로바로

요즘 AI 정말 좋네요

박명수다.

 

영감을 얻은 것은 스폰지밥에 나오는 마법의 소라고동이다.

 

애플리케이션 요구 사항은 다음과 같다:

1. 사용자가 직접 원하는 말투나, 성격, 답변 규칙을 지정할 수 있어야 한다.
2. 사용자가 마법의 소라고동책처럼 미리 고정된 답변을 추가할 수 있어야 한다.
3. 미리 지정된 고정 답변들 중 사용자의 질문에 대한 답이 될 수 있는 최적의 후보를 찾고, 최고점이 0.7을 넘기지 않는 경우에는 사용자가 입력한 말투, 성격, 답변 규칙에 따라 직접 답변을 생성한다.

대충 박명수를 흉내낼 페르소나를 설계해 준다:

@Builder
public record PersonaContext(
    String name,
    String description,
    String tone,
    String rules,
    List<String> quotes,
    List<StyleExampleContext> styleExamples
) { }

 

그리고 요구 사항을 만족하기 위해 다음과 같은 행동들을 수행할 수 있어야 한다:

- 페르소나 정보 조회 (입력: 페르소나 식별자, 출력: 페르소나 정보)
- 고정 답변 기반 응답 생성 (입력: 페르소나 정보, 사용자 질문, 출력: 질문에 대한 응답)
- 페르소나 기반 응답 생성 (입력: 페르소나 정보, 사용자 질문, 출력: 질문에 대한 응답)

 

우선 MagicConchAgent라는 클래스를 정의하고 설명을 추가해 준다.

@Slf4j
@RequiredArgsConstructor
@Agent(description = "Generate answer for user's question")
public class MagicConchAgent {}

 

페르소나 정보 조회 Action은 다음과 같이 정의한다 💨

    @Transactional
    @Action
    public PersonaContext searchContext(Long personaId) {
        Persona persona = personaRepository.findById(personaId)
                                           .orElseThrow();

        return PersonaContext.fromEntity(persona);
    }

 

그리고 고정 답변 기반 응답 생성 Action과  페르소나 기반 응답 생성 Action을 각각 구현한다.

    @Action
    public QuoteBasedAnswer createQuoteBasedAnswer(
        PersonaContext personaContext,
        String question,
        Ai ai
    ) {
        if (personaContext.quotes().isEmpty()) {
            return new QuoteBasedAnswer(null, 0);
        }

        String quotesText = personaContext.buildQuotesText();
        String prompt = QUOTE_BASED_PROMPT.formatted(question, quotesText);

        QuoteScoreList result = ai
            .withAutoLlm()
            .createObject(prompt, QuoteScoreList.class);

        QuoteScoreResult best = result.scores()
                                      .stream()
                                      .max((a, b) -> Double.compare(a.score(), b.score()))
                                      .orElseThrow();


        if (best.quoteIndex() <= 0 || best.quoteIndex() > personaContext.quotes().size()) {
            return new QuoteBasedAnswer(null, 0);
        }

        String bestQuote = personaContext.quotes().get(best.quoteIndex() - 1);

        return new QuoteBasedAnswer(bestQuote, best.score());
    }

 

    @Action
    public Optional<PersonaBasedAnswer> createPersonBasedAnswer(
        PersonaContext personaContext,
        QuoteBasedAnswer quoteBasedAnswer,
        String question,
        Ai ai
    ) {
        if (quoteBasedAnswer.score >= 0.7) {
            return Optional.empty();
        }

        String examples = personaContext.buildStyleExamplesText();

        String prompt = PERSONA_BASED_PROMPT.formatted(
            personaContext.name(),
            personaContext.description(),
            personaContext.tone(),
            personaContext.rules(),
            examples,
            question
        );

        String answer = ai.withAutoLlm().createObject(prompt, String.class);
        return Optional.of(new PersonaBasedAnswer(answer));
    }

 

그러면 Optional<PersonaBasedAnswer>와 QuoteBasedAnswer를 입력받는 최종 Action을 정의할 수 있다.

    @AchievesGoal(description = "answer user's question.")
    @Action
    public ConchAnswerResult conchAnswerResult(
        QuoteBasedAnswer quoteBasedAnswer,
        Optional<PersonaBasedAnswer> personaBasedAnswer
    ) {
        String answer = personaBasedAnswer.map(PersonaBasedAnswer::answer)
                                          .orElse(quoteBasedAnswer.answer());
        return new ConchAnswerResult(answer);
    }

 

코드에서 냄새가 난다고 느꼈다면 아주 정확하다… 🧀🧀

😒 Embabel 그렇게 쓰는 거 아닌데

소개에서 말했듯 에이전틱 AI의 핵심은 예외 상황이나 예상치 못한 결과에 대한 대응 능력이다. 현재 코드에서 quoteBasedAnswer.score >= 0.7 조건을 체크하여 답변을 생성할지 말지 결정하고 있지만, 만약 생성된 답변마저 품질이 낮아 다시 생성해야 하는 상황이 발생하면 일반적인 액션 구조로는 이를 처리하기 매우 까다롭다. 

 

https://docs.embabel.com/embabel-agent/guide/0.3.5-SNAPSHOT/#reference.states

Embabel Agent Framework User Guide

 

그래서 가이드 문서에 명시된대로 Embabel에서 제공하는 기능들을 사용하면 아주 쉽게 루프를 표현할 수 있다.

대충 흐름을 먼저 그려 보면 이런 느낌이다.

고정 답변 기반으로 적절한 응답을 찾고, 적절한 값이 없는 경우에는 적합도가 0.7 이상인 답변이 나올 때까지 AI 잡도리를 하는 구조이다👀

 

1. 공통 인터페이스

@State
public interface MagicConchState {
}

 

2. 고정 답변 기반 응답 생성 단계

public record SearchingQuote(
    PersonaContext context,
    String question
) implements MagicConchState {


    @Action
    public MagicConchState searchFromQuotes(Ai ai) {

        if (context.quotes().isEmpty()) {
            return new GeneratingAnswer(context, question, "사용 가능한 쿼트가 없습니다.");
        }

        QuoteScoreList result = ai.withAutoLlm()
                                  .createObject(
                                      QUOTE_BASED_PROMPT.formatted(
                                          question,
                                          context.buildQuotesText()
                                      ),
                                      QuoteScoreList.class
                                  );

        QuoteScoreResult best = result.scores().stream()
                                      .max(Comparator.comparingDouble(QuoteScoreResult::score))
                                      .orElseThrow();

        if (best.score() >= 0.7) {
            String quote = context.quotes().get(best.quoteIndex() - 1);
            return new FinalAnswer(quote);
        }

        return new GeneratingAnswer(context, question,
            "적절한 쿼트를 찾지 못했습니다 (최고점: " + best.score() + ")");
    }


    record QuoteScoreResult(
        int quoteIndex,
        double score
    ) {
    }

    record QuoteScoreList(
        List<QuoteScoreResult> scores
    ) {
    }
}

 

3. 페르소나 기반 응답 직접 생성 단계

public record GeneratingAnswer(
    PersonaContext context,
    String question,
    String reason
) implements MagicConchState {

    @Action
    public EvaluatingAnswer generate(Ai ai) {

        String prompt = PERSONA_BASED_PROMPT.formatted(
            context.name(),
            context.description(),
            context.tone(),
            context.rules(),
            context.buildStyleExamplesText(),
            question
        );

        String generated = ai.withAutoLlm()
                             .withLlm(LlmOptions.withAutoLlm().withTemperature(0.8))
                             .createObject(prompt, String.class);

        return new EvaluatingAnswer(context, question, generated);
    }
}

 

4. 답변 평가 단계

@Slf4j
public record EvaluatingAnswer(
    PersonaContext context,
    String question,
    String candidateAnswer
) implements MagicConchState {

    @Action(clearBlackboard = true)
    public MagicConchState evaluate(Ai ai) {

        Double qualityScore = ai.withAutoLlm()
                                .createObject(
                                    "다음 답변이 페르소나 설정에 얼마나 부합하는지 점수(0.0~1.0)만 출력해줘: "
                                        + candidateAnswer,
                                    Double.class
                                );

        if (qualityScore >= 0.7) {
            return new FinalAnswer(candidateAnswer);
        }

        log.info("[MagicConch] 품질 미달({}), 다시 생성합니다.", qualityScore);

        return new GeneratingAnswer(context, question, "품질 평가 실패");
    }
}

❗️여기서 @Action에 clearBlackboard=true라는 속성을 사용하는데, 이게 에이전트가 루프를 수행할 수 있게 만드는 핵심 장치이다.

(근데 진짜 blackboard라고 한 거 진짜 레전드 찰떡콩떡 네이밍…)

 

1. 중복 타입에 의한 실행 차단 방지 역할

Emababel의 GOAP 플래너는 블랙보드에 특정 타입의 객체가 이미 존재하면, 해당 목표가 이미 달성되었다고 판단하여 그 객체를 생성하는 액션을 다시 실행하지 않으려고 한다. 

 

만약 clearBlackboard를 설정하지 않는다면, 두 번째 루프에서 플래너는 블랙보드에 이미 이전 단계의 GeneratingAnswer나 EvaluatingAnswer 객체가 남아 있는 것을 보고, 이미 해당 단계들을 거쳤으니 다시 생생할 필요가 없다고 판단하여 프로세스가 멈추거나 제대로 작동하지 않게 된다.

 

clearBlackboard=true를 설정하면 액션의 결과물(이 경우 새로운 GeneratingAnswer 또는 FinalAnswer 객체)를 제외한 나머지 모든 중간 데이터가 블랙보드에서 제거되므로, 플래너가 우리의 의도대로 다시 계획을 수립하는 유연한 구조이다.

 

2. 실행 이력(hasRun) 리셋

Embabel은 액션의 무한 반복을 막기 위해 각 액션의 실행 여부를 hasRun이라는 조건으로 추적한다. 평가 결과가 기준 미달이어서 다시 생성 단계로 돌아가야 하는 경우, 이전에 실행했던 generate 액션을 다시 실행해야 하는데, 이때 블랙보드를 비워주면 hasRun 추적 조건들도 함께 제거되어서 플래너가 이전에 실행했던 액션들을 다시 실행 경로에 포함시킬 수 있게 된다 👍

 

 

5. 최종 답변 확정 단계

public record FinalAnswer(
    String answer
) implements MagicConchState {

    @AchievesGoal(description = "사용자 질문에 대한 최종 답변 확정")
    @Action
    public ConchAnswerResult finalizeAnswer() {
        return new ConchAnswerResult(answer);
    }
}

 

마지막으로 진입점이 될 Agent를 정의한다:

@Agent(description = "Generate answer for user's question")
@RequiredArgsConstructor
public class MagicConchAgent {

    private final PersonaRepository personaRepository;

    @Action
    @Transactional
    public SearchingQuote start(Long personaId, String question) {
        Persona persona = personaRepository.findById(personaId).orElseThrow();
        return new SearchingQuote(PersonaContext.fromEntity(persona), question);
    }
}

 

근데 여기서 잠깐

분명 AchievesGoal이 없는 Agent는 이빨 빠진 호랑이, 튀김옷 없는 치킨, 리바이 없는 조사병단, 주디 없는 닉이랬는데…

 

 

충격 AchievesGoal이 없는 Agent 실존!

이유는 다음과 같다:

Agent의 반환값인 SearchingQuote는 MagicConchState를 구현하는데, MagicConchState는 @State 어노테이션이 붙어 있기 때문에 MagicConchState의 구현체들 중 FinalAnswer가 @AchievesGoal을 가지고 있으면 Embabel은 알아서 경로를 추론할 수 있다.

 

호기심에 MagicConchState에서 @State 어노테이션을 제거하고 애플리케이션을 실행해 봤는데

Embabel이 바로 화를 냈다 😥  

 

물론 모든 Action을 Agent에 때려넣고 타입 기반 추적으로 @State 없이도 구현이 가능하다. (아래는 초반에 문서를 대충 읽고 냅다 구현부터 하는 바람에 탄생한 리팩토링 전 코드이다. state record는 거둘 뿐… 나는 모든 책임을 MagicConchAgent에게 위임한다)

@Slf4j
@RequiredArgsConstructor
@Agent(description = "Generate answer for user's question")
public class MagicConchAgent {

    private final PersonaRepository personaRepository;

    @Transactional
    @Action
    public SearchingQuote initContext(Long personaId, String question) {
        Persona persona = personaRepository.findById(personaId).orElseThrow();
        return new SearchingQuote(PersonaContext.fromEntity(persona), question);
    }

    @Action
    public MagicConchState searchFromQuotes(SearchingQuote search, Ai ai) {
        PersonaContext ctx = search.context();
        if (ctx.quotes().isEmpty()) {
            return new GeneratingAnswer(ctx, search.question(), "사용 가능한 쿼트가 없습니다.");
        }

        QuoteScoreList result = ai.withAutoLlm()
                                  .createObject(QUOTE_BASED_PROMPT.formatted(search.question(), ctx.buildQuotesText()), QuoteScoreList.class);

        QuoteScoreResult best = result.scores().stream()
                                      .max(Comparator.comparingDouble(QuoteScoreResult::score))
                                      .orElseThrow();

        if (best.score() >= 0.7) {
            String quote = ctx.quotes().get(best.quoteIndex() - 1);
            return new FinalAnswer(quote); // 바로 목표 타입 반환 가능
        }

        return new GeneratingAnswer(ctx, search.question(), "적절한 쿼트를 찾지 못했습니다 (최고점: " + best.score() + ")");
    }

    @Action
    public EvaluatingAnswer generateByPersona(GeneratingAnswer generating, Ai ai) {
        PersonaContext ctx = generating.context();
        String prompt = PERSONA_BASED_PROMPT.formatted(
            ctx.name(), ctx.description(), ctx.tone(), ctx.rules(), ctx.buildStyleExamplesText(), generating.question()
        );

        String generated = ai.withAutoLlm()
                             .withLlm(LlmOptions.withAutoLlm().withTemperature(0.8)) // 생성 시 창의성 부여
                             .createObject(prompt, String.class);

        return new EvaluatingAnswer(ctx, generating.question(), generated);
    }

    @Action(clearBlackboard = true) // 루프를 위해 이전 상태들을 비움
    public MagicConchState evaluateGeneratedAnswer(EvaluatingAnswer evaluation, Ai ai) {
        Double qualityScore = ai.withAutoLlm().createObject(
            "다음 답변이 페르소나 설정에 얼마나 부합하는지 점수(0.0~1.0)만 출력해줘: " + evaluation.candidateAnswer(),
            Double.class
        );

        if (qualityScore >= 0.7) {
            return new FinalAnswer(evaluation.candidateAnswer());
        }

        log.info("[MagicConch] 품질 미달({}), 다시 생성합니다.", qualityScore);
        return new GeneratingAnswer(evaluation.context(), evaluation.question(), "이전 생성 답변의 품질이 낮음");
    }


    @AchievesGoal(description = "사용자 질문에 대한 최종 답변 확정")
    @Action
    public ConchAnswerResult finalize(FinalAnswer result) {
        return new ConchAnswerResult(result.answer);
    }

    // ❗️❗️❗️ @State 어노테이션 제거 ❗️❗️❗️
    public interface MagicConchState {
    }
}

 

물론 이게 보기 좋은 코드도 아니고 유지보수를 하기에 좋은 코드는 더더욱 아니긴 하지만, 어쨌든 이렇게 개떡 같이 짜고 실행시켜도 똑똑한 Embabel이 입력 타입과 출력 타입 매핑으로 기능이 잘 돌아가서 @State를 왜 써야 하는지? 에 대한 의문이 자연스럽게 생겼다. (코드로 똥을 쌌지만 더 깊은 학습을 할 수 있다니 완전 럭키비키니시티자나🧽)

 

1. 상태 스코핑

@State를 사용해야 하는 가장 결정적인 이유는 경로 격리이다. @State가 없으면 플래너는 매 단계마다 에이전트에 정의된 모든 액션을 검토하여 다음 경로를 찾는다. 문제는 액션이 10개, 20개로 늘어나면 플래너가 엉뚱한 액션을 선택할 가능성이 생기고, 판단에 걸리는 비용 문제도 있다. 그러나 액션이 @State 객체를 반환하면, 플래너는 해당 상태 클래스 내부에 정의된 액션들만 실행 후보로 고르려고 하기 때문에 상태 스코핑이 아주 큰 장점이라고 볼 수 있다.

 

2. 상태 숨김

@State를 사용하면 프레임워크가 상태 전이 시 이전 상태 객체들을 자동으로 숨김처리한다. 이전 상태는 블랙보드 history에는 남지만, 플래너의 눈에는 보이지 않게 되어서 다음 단계의 의사 결정을 방해하지 않는다. 즉, 하나의 State 구현체만이 플래너의 의사 결정에 관여하게 된다.

 

3. 유지보수와 관심사의 분리

모든 로직을 에이전트에 때려 넣으면 코드가 비대해지고 각 단계 간의 경계가 모호해진다. 잘 만들어진 EvaluatingAnswer 상태 클래스는 다른 에이전트에서도 그대로 가져다 쓰거나 상속받아 기능을 확장하기 매우 용이한 구조가 된다.

 

⚒️ 도구 쥐여주기

똑똑해지지 마, 아니 똑똑해져, 아니 똑똑해지지 마, 내 밥그릇 빼앗지 않을 만큼만 똑똑해져

 

Embabel 프레임워크에서 도메인 객체들은 단순한 데이터 덩어리가 아니다. 선택적으로 도메인이 할 수 있는 행동을 LLM에게 알려주어서 에이전트가 Action을 수행하는 동안 도메인과 상호작용을 할 수 있다는 특징이 있다.

 

다음과 같이 인터뷰 전체 컨텍스트를 저장하는 레코드가 있을 때, 인터뷰에 대한 어떠한 요약 정보나 다음 질문 추천을 받고 싶은 경우 어떤 정보를 넣어줘야 할까?

public record InterviewContext(
    CandidateAnalysisResult candidateAnalysis,
    PositionAnalysisResult positionAnalysis,
    List<EvaluationCategoryResult> evaluationCategories,
    List<String> checklist,
    List<AskedQuestionResult> history
) {
}

 

정해진 답은 없다. 현재 인터뷰의 진행 상황이나, 지원자의 특징, 공고의 특징 등에 따라 어떤 정보는 AI의 의사 결정에 도움이 되고 어떤 정보는 아닐 것이다. 예를 들어, 면접 질문을 추천해 달라고 요청했을 경우 면접관의 질문에 대한 지원자의 마지막 답변이 연이은 꼬리 질문을 생성하기 어려운 답변일 경우 (ex. 잘 모르겠습니다.), AI는 추가 질문 생성을 위해 전체 공고와 지원자의 요약 정보를 추가로 필요로 할 것이고, 반대로 마지막 문답이 꼬리 질문을 생성하기에 적합한 경우에는 굳이 전체 면접 컨텍스트를 확인할 필요가 없다. LLM은 똑똑하기 때문에, 판단 과정에서 자신이 어떤 정보가 더 부가적으로 필요한지, 혹은 현재 정보로도 충분히 만족스러운 답변을 뱉을 수 있는지를 추론할 수 있다. 따라서 우리는 InterviewContext에 있는 모든 내용을 모조리 LLM에게 전달하고 프롬프트를 작성하는 대신, 다음과 같이 InterviewContext에 도구를 추가할 수 있다.

public record InterviewContext(
    CandidateAnalysisResult candidateAnalysis,
    PositionAnalysisResult positionAnalysis,
    List<EvaluationCategoryResult> evaluationCategories,
    List<String> checklist,
    List<AskedQuestionResult> history
) {

    @LlmTool(description = "Get detailed candidate analysis")
    public CandidateAnalysisResult getCandidateAnalysis() {
        return candidateAnalysis;
    }

    @LlmTool(description = "Get detailed position or purpose analysis")
    public PositionAnalysisResult getPositionAnalysis() {
        return positionAnalysis;
    }

    @LlmTool(description = "Get the most recent interview question and answers")
    public AskedQuestionResult getLastInteraction() {
        if (history.isEmpty()) {
            return null;
        }
        return history.getLast();
    }

    @LlmTool(description = "Get previous interaction by index. 0 is the first question.")
    public AskedQuestionResult getInteraction(int index) {
        if (index < 0 || index >= history.size()) {
            return null;
        }
        return history.get(index);
    }

    @LlmTool(description = "Get recent interview interactions")
    public List<AskedQuestionResult> getRecentHistory(int count) {
        int start = Math.max(0, history.size() - count);
        return history.subList(start, history.size());
    }

    @LlmTool(description = "Search interview history by keyword")
    public List<AskedQuestionResult> searchHistory(String keyword) {
        return history.stream()
                      .filter(q -> q.content().toLowerCase().contains(keyword.toLowerCase()))
                      .toList();
    }

    @LlmTool(description = "Get evaluation categories used to score the candidate")
    public List<EvaluationCategoryResult> getEvaluationCategories() {
        return evaluationCategories;
    }

    @LlmTool(description = "Get checklist topics that interview questions should cover")
    public List<String> getChecklist() {
        return checklist;
    }

    public String toSummary() {
        return """
               Candidate: %s
               Position: %s
               Categories: %d
               Checklist topics: %d
               """.formatted(
            candidateAnalysis.summary(),
            positionAnalysis.summary(),
            evaluationCategories.size(),
            checklist.size()
        );
    }
}

 

이렇게 코드를 작성해서 기본적으로는 Summary만 프롬프트에 입력해 주어도, LLM이 필요에 의해 알아서 도구를 주섬주섬 찾아서 쓰기 때문에 전체 컨텍스트를 입력하는 경우보다 훨씬 효율적이다.

 

이 LLM이 판단 과정에서 이 객체를 사용하게 만들고 싶으면 그냥 .withToolObject에 넣어주면 땡이다. 요로코롬

            String[] generated = ai.withAutoLlm()
                                   .withToolObject(context)
                                   .createObject(prompt, String[].class);

참 쉽죠? ^^

번외) MCP (Model Context Protocol)

도구를 호스팅하고 공유하기 위한 표준화된 프로토콜인데, 아주 살짝 보여주자면

@Configuration
public class NotionMcpConfig {

    @Bean
    public McpToolFactory mcpToolFactory(List<McpSyncClient> clients) {
        return new McpToolFactory(clients);
    }

    @Bean(name = "notionTool")
    public Tool notionTool(McpToolFactory mcpToolFactory) {
        return mcpToolFactory.matryoshka(
            "notion",
            "Notion MCP editing tool",
            callback -> true
        );
    }
}

NotionTool을 Bean으로 등록하고 그걸 도구로 등록해 주면

@Agent(description = "Exports evaluation result to Notion")
@RequiredArgsConstructor
public class EvaluationNotionAgent {

    private final Tool notionTool;

    @AchievesGoal(description = "Exported to Notion")
    @Action
    public String export(Long candidateId, EvaluationResult result, Ai ai) {
        String categoryTable = result.categoryScores().stream()
                                     .map(c -> "%s | %.1f | %.1f | %s".formatted(
                                         c.content(),
                                         c.weight(),
                                         c.score(),
                                         c.rationale()
                                     ))
                                     .collect(Collectors.joining("\n"));

        String evaluationData = FORMAT_STRING.formatted(
            result.totalScore(),
            categoryTable,
            result.interviewAssessment(),
            result.strengths(),
            result.weaknesses(),
            result.hiringRecommendation()
        );

        return ai.withAutoLlm()
                 .withTool(notionTool)
                 .createObject(NOTION_PROMPT.formatted(pageId, candidateId, evaluationData), String.class);
    }
}

 

대충 이런 느낌으로 애플리케이션 API 호출 시 AI가 알아서 노션을 업데이트해주는 것도 가능하다:

근데 토큰이 살살 녹으니까 주의하세요

 

 

박명수_최종.png

 

 

참고자료

https://docs.embabel.com/embabel-agent/guide/0.3.5-SNAPSHOT/#superior-extensibility-and-reuse