AIchain Agent: 계획, 실행, 성찰 (Plan, Act, Reflect)

**Chain (체인)**은 실행되기 전에 모든 단계를 알고 있습니다. 첫 번째 단계, 두 번째 단계, 세 번째 단계를 정의하면 순서대로 실행합니다. 이는 문제가 잘 파악되어 있을 때 유효합니다. 하지만 단계를 사전에 알 수 없다면 어떻게 될까요? 한 단계의 결과에 따라 두 단계가 더 필요할지, 아니면 다섯 단계가 더 필요할지가 결정된다면 어떨까요? 검색 결과가 유용한 것을 반환하지 않아 실행 도중에 접근 방식 전체를 바꿔야 한다면 어떻게 될까요?

그 지점에서 **Agent (에이전트)**가 등장합니다. 에이전트는 계획을 세우고, 발생한 일을 관찰하며, 다음에 무엇을 할지 결정합니다. Chain과 Agent의 차이는 스크립트(script)와 사고(thinking)의 차이와 같습니다.

에이전트가 해결하는 문제

result 객체는 주의 깊게 살펴볼 만한 세 가지 정보를 제공합니다: .output (최종 답변), .steps_taken (실제로 실행된 단계 수), 그리고 .tokens_used (소비된 총 토큰 수)입니다. 이는 어떤 일이 일어났고 비용이 얼마나 들었는지 이해하기에 충분합니다.

두 가지 모드: 고정 계획(Fixed-Plan) 및 적응형(Adaptive)

yait_aichain의 에이전트는 두 가지 실행 모드를 지원하며, 이들 사이의 선택이 에이전트의 동작 방식을 결정합니다.

고정 계획 (Fixed-Plan, waterfall)

폭포수(waterfall) 모드에서 에이전트는 아무것도 실행하기 전에 완전한 계획을 수립합니다. 모든 단계가 사전에 배치된 후 순서대로 실행됩니다. 계획 구조는 고정되어 있지만, 단계 사이에서 성찰(reflection)은 여전히 발생합니다. 즉, 에이전트는 작업이 이미 완료되었다면 조기에 종료하거나, 실패한 단계를 재시도할 수 있습니다. 다만, 새로운 단계를 추가하거나 남은 단계들의 순서를 재배치할 수는 없습니다.

이는 예측 가능성을 제공합니다. 계획을 보고 에이전트가 대략 무엇을 할지 알 수 있습니다. 검색이 재시도가 필요할지 확실하지 않더라도, "검색 후 요약, 그 다음 형식화"와 같이 작업에 자연스러운 구조가 있는 경우 적절한 선택입니다.

적응형 (Adaptive, agile)

애자일(Agile) 모드는 다릅니다. 매 단계가 끝날 때마다 에이전트는 방금 일어난 일을 살펴보고 남은 모든 단계를 다시 작성할 수 있습니다. 예를 들어, 첫 번째 검색 결과 질문이 두 부분으로 구성되어 있다는 사실이 밝혀지면, 에이전트는 원래 계획에 없던 두 번째 검색을 추가할 수 있습니다. 혹은 어떤 단계가 정확히 필요한 결과를 반환했다면, 에이전트는 계획된 세 단계를 건너뛰고 즉시 최종 답변으로 넘어갈 수도 있습니다.

다음은 여러 도구를 사용하는 적응형 에이전트의 예시입니다:

import os
from yait_aichain.models import Model
from yait_aichain.agent import Agent
...

이 에이전트는 세 가지 도구를 가지고 있습니다. searchPerplexity는 URL을 찾습니다. fetchPage는 페이지의 원문 콘텐츠를 가져옵니다. convertToMD는 모델이 구조를 깔끔하게 읽을 수 있도록 HTML을 마크다운(Markdown)으로 변환합니다. 에이전트는 각 단계에서 어떤 도구를 호출할지 스스로 결정하며, 각 도구가 반환하는 결과에 따라 계획을 변경할 수 있습니다.

그러한 유연성에는 대가가 따릅니다. 실행 경로를 예측하기가 더 어려워지며, 에이전트가 성과가 없는 접근 방식을 탐색하느라 더 많은 토큰 (tokens)을 소모할 수 있습니다.

작업의 형태가 이미 알려져 있다면 폭포수 (waterfall) 방식을 사용하세요. 그렇지 않다면 애자일 (agile) 방식을 사용하세요.

max_steps는 선택 사항이 아닙니다

max_steps가 없는 에이전트는 무한 루프에 빠지기 직전의 상태와 같습니다.

엄격한 제한 (hard cap)이 없다면, 에이전트는 모델의 컨텍스트 윈도우 (context window)를 모두 소진하거나 토큰 예산을 다 쓸 때까지 계획과 실행을 반복합니다. 개발 단계에서는 이는 어색한 대기 시간과 예상치 못한 비용 청구로 이어지며, 운영 (production) 단계에서는 서비스 중단 (outage)을 의미합니다.

# max_steps가 누락되었습니다. 에이전트는 무언가 고장 날 때까지 실행됩니다.
agent = Agent(
    orchestrator=Model("claude-sonnet-4-6", api_key=os.getenv("ANTHROPIC_API_KEY")),
...

항상 max_steps를 설정하십시오. "검색 및 요약"과 같은 단일 도구 작업의 경우, 5단계 정도면 한 번의 검색, 가능한 재시도, 그리고 여유 있는 합성 단계를 모두 커버할 수 있습니다. 검색, 가져오기, 변환, 분석과 같은 다중 도구 워크플로 (multi-tool workflows)의 경우, 에이전트가 통제 불능 상태로 빠지지 않으면서도 현실적인 단계 수를 반영할 수 있도록 8~10단계를 설정하십시오.

또한 에이전트가 작업을 마치기 전에 한계치에 도달했는지 확인해야 합니다:

if result.steps_taken == max_steps:
    # 에이전트가 작업을 완료하기 전에 단계를 모두 소진했습니다.
    # 로그를 남기거나, 더 높은 제한값으로 재시도하거나, 사용자에게 에러를 표시하십시오.
...

이 확인 과정을 생략하지 마십시오. max_steps에 도달한 에이전트는 그럴듯해 보이지만 불완전한 답변을 반환할 수 있으며, 직접 확인하지 않는 한 이를 알 수 없습니다.

에이전트 (Agent) vs 체인 (Chain) 언제 무엇을 사용할 것인가

단계가 이미 정해져 있다면 체인 (Chain)을 사용하십시오. 체인은 결정론적 (deterministic)이며, 더 저렴하고, 디버깅이 쉽습니다. 언제나 그렇습니다.

실행이 시작되기 전에 단계의 수나 성격을 결정할 수 없는 경우 — 즉, 작업이 중간 결과에 반응해야 하거나 질문에서 답변으로 가는 경로가 직선이 아닌 경우에는 에이전트 (Agent)를 사용하십시오.

저의 실질적인 휴리스틱(Heuristic): 만약 코드를 작성하기 전에 화이트보드에 워크플로(Workflow)를 그릴 수 있다면, 그것은 체인(Chain)입니다. 만약 그 사이에 "상황에 따라 다름"이라는 화살표를 사용하여 여러 가지 가능한 워크플로를 그려야 한다면, 그것은 에이전트(Agent)입니다.

전체 API 표면 (The Full API Surface)

참고를 위해, 설정 가능한 항목은 다음과 같습니다:

Agent(
    orchestrator: Model,        # 필수 — 계획 및 성찰 (plans and reflects)
    executors:    list[Model],  # 선택 사항 — 도구 호출 (tool-call) 단계를 위한 더 저렴한 모델들
...

executors 파라미터를 사용하면, 더 유능한 모델을 오케스트레이터 (orchestrator)로 유지하면서, 개별적인 도구 호출 (tool-call) 단계에는 더 저렴하거나 빠른 모델을 할당할 수 있습니다:

import os
from yait_aichain.models import Model
from yait_aichain.agent import Agent
...

오케스트레이터 (orchestrator)는 다음에 무엇을 할지 결정하고, 결과를 평가하며, 최종 답변을 작성하는 것과 같이 추론 집약적인 작업을 처리합니다. 실행자 (executor)는 그 사이의 기계적인 단계, 즉 도구를 호출하고 출력을 다시 전달하는 작업을 처리합니다. 중요한 부분에는 유능한 모델을, 그렇지 않은 부분에는 더 빠르고 저렴한 모델을 사용하는 것입니다. 이러한 분할만으로도 더 긴 워크플로 (workflow)에서 비용을 의미 있게 절감할 수 있습니다.