Skip to content

CrewAI 에이전트 (Agents)

여러 개의 LLM을 한 팀처럼 굴리고 싶을 때, 우리는 각각의 LLM에게 "이 일은 네가 해"라고 역할을 나눠주죠. 문제는 이렇게 하면 "이 조사 결과를 보고서로 정리해 줘" 같은 식으로 사람이 중간마다 손을 대야 한다는 거예요. CrewAI에서는 이걸 에이전트(Agent) 라는 단위로 만들어, 사람 개입 없이 스스로 일하고 서로 협력하도록 구성해요. 이걸 '팀'이 아니라 '크루(crew)'라 부르는 이유도 그래요 — 각자 전문 분야를 가진 팀원들이 모여 한 임무를 수행하는 구조거든요.

에이전트가 뭘 할 수 있나요

CrewAI 공식 문서에 따르면, 에이전트는 자기 스스로 다음을 할 수 있는 자율적인 단위예요.

  • 주어진 특정 작업을 수행해요
  • 자신의 역할과 목표에 따라 결정을 내려요
  • 도구(tool)를 사용해서 목표를 달성해요
  • 다른 에이전트와 소통하고 협력해요
  • 상호작용을 기억(memory)으로 유지해요
  • 허용되면 작업을 다른 에이전트에게 위임해요

쉽게 말하면, 에이전트는 특정 스킬과 책임을 가진 전담 팀원이에요. 예를 들어 Researcher(조사 담당) 에이전트는 정보를 모으고 분석하는 데 강하고, Writer(작성 담당) 에이전트는 콘텐츠를 만드는 데 더 낫죠. 문서에서는 이 비유를 강조해요 — 팀워크의 '역할'을 코드로 만든 게 에이전트예요.

에이전트를 정의하는 핵심 속성

에이전트는 주로 다음 속성들로 구성돼요. 처음엔 전부 외울 필요 없고, role, goal, backstory 세 개가 기본이라는 것만 잡으면 돼요.

속성 파라미터 설명
역할 role 크루 안에서 에이전트가 맡는 기능과 전문 분야
목표 goal 에이전트의 의사결정을 이끄는 개별 목표
배경 스토리 backstory 에이전트의 성격과 맥락을 만들어 상호작용을 풍부하게 함
LLM (선택) llm 에이전트를 구동하는 언어 모델. 기본값은 OPENAI_MODEL_NAME에 지정된 모델 또는 "gpt-4"
도구 (선택) tools 에이전트가 쓸 수 있는 기능. 기본값은 빈 목록
함수 호출 LLM (선택) function_calling_llm 도구 호출용 언어 모델. 지정하면 크루의 LLM을 덮어씀
최대 반복 (선택) max_iter 최선의 답을 내기까지 허용하는 반복 횟수. 기본 20
최대 RPM (선택) max_rpm 분당 최대 요청 수. API 속도 제한을 피하는 데 사용
실행 시간 제한 (선택) max_execution_time 작업 실행 최대 시간(초)
상세 로그 (선택) verbose 디버깅용 상세 실행 로그. 기본 False
위임 허용 (선택) allow_delegation 다른 에이전트에게 작업을 위임할 수 있는지. 기본 False

role·goal·backstory는 필수(required) 라는 걸 기억하세요. 이 세 개가 에이전트의 행동을 만드는 뼈대예요.

코드로 에이전트 만들기

에이전트를 만드는 방법은 두 가지예요. 공식 문서는 YAML 설정을 권장하지만, 그냥 파이썬 코드 안에서 바로 Agent(...) 로 정의하는 방법도 자주 쓰여요. 실제 데이터스케쳐스에서 실무로 쓴다면 코드 한 줄로 만드는 아래 방식부터 익히는 게 자연스러워요.

from crewai import Agent
from crewai_tools import SerperDevTool

research_agent = Agent(
    role="Research Analyst",
    goal="Find and summarize information about specific topics",
    backstory="You are an experienced researcher with attention to detail",
    tools=[SerperDevTool()],
    verbose=True  # 디버깅용 로그 출력
)

이 코드에서 눈여겨볼 부분은 이렇게 두 가지예요.

  • tools=[SerperDevTool()] — 에이전트가 검색 도구를 쓸 수 있게 해줘요. 도구가 없다면 에이전트는 자기 훈련 데이터 안에서만 답을 찾아요.
  • verbose=True — 실행 중에 뭐가 벌어지는지 로그로 보여줘서, 처음 디버깅할 때 꽤 유용해요. 기본값은 False예요.

에이전트에 도구 붙이기와 기억 (Memory)

에이전트는 도구(tool) 라는 외부 능력을 장착할 수 있어요. CrewAI 툴킷이든 LangChain 도구든 가져다 쓸 수 있고요. 또 memory=True로 두면 에이전트가 여러 번의 상호작용 맥락을 기억해, 복잡한 다단계 작업을 훨씬 잘 처리해요.

from crewai import Agent

analyst = Agent(
    role="Data Analyst",
    goal="Analyze and remember complex data patterns",
    memory=True,  # 기억 활성화
    verbose=True
)

한 가지 주의할 점이 있어요. 대화가 길어지면 LLM의 컨텍스트 윈도우(한 번에 넣을 수 있는 토큰 범위) 를 넘어설 수 있는데, CrewAI는 이걸 자동으로 관리해줘요. respect_context_window=True(기본값)면 대화가 커지면 자동으로 요약하고, False로 두면 요약하지 않고 오류로 멈춰요. 큰 문서나 오래 이어지는 대화를 다룰 땐 기본값인 True가 안전해요.

데이터스케쳐스 실무 관점

가장 실용적인 사용법은 역할 분리를 코드로 고정하는 거예요. 조사 전담 에이전트와 작성 전담 에이전트를 각각 만들고, 조사는 SerperDevTool 같은 검색 도구를 주고, 작성에는 도구 없이 목표와 배경만 확실히 주는 식이에요. 그러면 프롬프트를 사람이 매번 새로 쓰는 대신, 에이전트 정의 하나로 팀의 업무 분담이 반복 재사용돼요. 다만 llm 기본값이 gpt-4로 잡혀 있다는 점, 그리고 우리가 쓰는 모델(예: 한국어 처리에 강한 모델)을 쓰려면 llm 파라미터를 명시적으로 넣어줘야 한다는 점은 처음에 꼭 확인해야 해요. 또 max_iter 기본값 20, max_rpm으로 속도 제한을 거는 것처럼 실행 비용과 시간을 잡아주는 파라미터도 실무에서 꼭 챙겨요.

더 알아보기