에이전트: 역할·목표·속성 가이드

에이전트: 역할·목표·속성 가이드

CrewAI의 에이전트(Agent)는 크루 안에서 특정 임무를 수행하는 자율 단위예요. 역할·목표·backstory를 기반으로 의사결정을 내리고, 툴을 쓰고, 다른 에이전트와 협업하며, 허용되면 작업을 위임하기도 합니다. 이 페이지에서는 에이전트의 전체 속성, 생성 방법(JSONC·클래식 YAML·코드), 컨텍스트 창 관리, 그리고 모범 사례를 정리합니다.

출처: 공식문서

본문

에이전트 개요

CrewAI 프레임워크에서 Agent는 다음을 할 수 있는 자율 단위입니다:

• 특정 태스크 수행
• 역할·목표에 기반한 의사결정
• 목표 달성을 위한 툴 사용
• 다른 에이전트와 소통·협업
• 상호작용 메모리 유지
• 허용되면 태스크 위임

에이전트 속성

에이전트 생성

에이전트를 만드는 두 가지 일반적인 방법: JSONC 프로젝트 구성(신규 크루 권장) 과 코드에서 직접 정의.

JSONC 구성(권장)

crewai create crew <name>으로 만든 새 프로젝트는 JSON-first 구성을 사용합니다. 각 에이전트는 agents/<agent_name>.jsonc에 정의되고, crew.jsonc가 어떤 에이전트가 크루에 속하는지 나열합니다.

agents/researcher.jsonc 예시:

{
  "role": "{topic} Senior Data Researcher",
  "goal": "Uncover cutting-edge developments in {topic}",
  "backstory": "You find the most relevant information and present it clearly.",
  "llm": "openai/gpt-4o",
  "tools": ["SerperDevTool"],
  "settings": {
    "verbose": true,
    "allow_delegation": false,
    "max_iter": 20
  }
}

그다음 crew.jsonc에서 그 에이전트를 포함합니다:

{
  "name": "Research Crew",
  "agents": ["researcher"],
  "tasks": [
    {
      "name": "research_task",
      "description": "Research {topic}",
      "expected_output": "A concise briefing about {topic}",
      "agent": "researcher"
    }
  ],
  "inputs": {
    "topic": "AI Agents"
  }
}

에이전트 파일은 공개 Agent 필드를 모두 지원합니다. verbose, allow_delegation, max_iter, max_rpm, memory, cache, planning_config, use_system_prompt 같은 동작 옵션은 최상위 또는 settings 아래 둘 수 있으며 settings 값이 우선합니다.

클래식 YAML 구성

crewai create crew <name> --classic으로 만든 클래식 프로젝트는 config/agents.yaml과 crew.py의 @CrewBase 클래스를 사용합니다. 파이썬 데코레이터나 기존 YAML 프로젝트를 원하는 팀을 위해 계속 지원됩니다.

코드 직접 정의

Agent 클래스를 인스턴스화해 코드로 직접 만들 수 있습니다. 모든 파라미터가 포함된 예시:

from crewai import Agent
from crewai_tools import SerperDevTool

# Create an agent with all available parameters
agent = Agent(
    role="Senior Data Scientist",
    goal="Analyze and interpret complex datasets to provide actionable insights",
    backstory="With over 10 years of experience in data science and machine learning, "
              "you excel at finding patterns in complex datasets.",
    llm="gpt-4",  # Default: OPENAI_MODEL_NAME or "gpt-4"
    function_calling_llm=None,  # Optional: Separate LLM for tool calling
    verbose=False,  # Default: False
    allow_delegation=False,  # Default: False
    max_iter=20,  # Default: 20 iterations
    max_rpm=None,  # Optional: Rate limit for API calls
    max_execution_time=None,  # Optional: Maximum execution time in seconds
    max_retry_limit=2,  # Default: 2 retries on error
    allow_code_execution=False,  # Default: False
    code_execution_mode="safe",  # Default: "safe" (options: "safe", "unsafe")
    respect_context_window=True,  # Default: True
    use_system_prompt=True,  # Default: True
    multimodal=False,  # Default: False
    inject_date=False,  # Default: False
    date_format="%Y-%m-%d",  # Default: ISO format
    reasoning=False,  # Default: False
    max_reasoning_attempts=None,  # Default: None
    tools=[SerperDevTool()],  # Optional: List of tools
    knowledge_sources=None,  # Optional: List of knowledge sources
    embedder=None,  # Optional: Custom embedder configuration
    system_template=None,  # Optional: Custom system prompt template
    prompt_template=None,  # Optional: Custom prompt template
    response_template=None,  # Optional: Custom response template
    step_callback=None,  # Optional: Callback function for monitoring
)

파라미터 상세

• 핵심 파라미터: role, goal, backstory는 필수이며 에이전트 동작을 결정. llm은 사용 언어모델 결정(기본 OpenAI GPT-4).
• 메모리·컨텍스트: memory로 대화 이력 유지, respect_context_window로 토큰 한도 문제 방지, knowledge_sources로 도메인 지식베이스 추가.
• 실행 제어: max_iter(최선의 답 전 최대 시도), max_execution_time(초 단위 타임아웃), max_rpm(API 레이트 리밋), max_retry_limit(오류 재시도).
• 코드 실행: allow_code_execution, code_execution_mode는 폐기되었고 CodeInterpreterTool이 crewai-tools에서 제거됨. 안전한 코드 실행에는 E2B 또는 Modal 같은 전용 샌드박스 서비스를 사용하세요.
• 고급 기능: multimodal(텍스트·비주얼 처리), reasoning(실행 전 반성·계획), inject_date(프롬프트에 현재 날짜 주입).
• 템플릿: system_template(핵심 동작), prompt_template(입력 형식), response_template(응답 형식).

에이전트 툴

에이전트는 CrewAI Toolkit과 LangChain Tools의 툴로 강화될 수 있습니다.

from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools

# Create tools
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()

# Add tools to agent
researcher = Agent(
    role="AI Technology Researcher",
    goal="Research the latest AI developments",
    tools=[search_tool, wiki_tool],
    verbose=True
)

에이전트 메모리와 컨텍스트

에이전트는 상호작용 메모리와 이전 태스크 컨텍스트를 유지할 수 있습니다. memory=True로 설정하면 여러 상호작용에 걸쳐 컨텍스트를 유지해 복잡한 다단계 태스크를 더 잘 처리합니다.

컨텍스트 창 관리

CrewAI는 대화가 LLM의 토큰 한도를 초과할 때 처리하는 정교한 자동 컨텍스트 창 관리를 포함합니다. respect_context_window 파라미터로 제어됩니다.

• respect_context_window=True(기본·권장): 에이전트 대화 이력이 컨텍스트 창에 비대해지면 CrewAI가 자동 감지해 요약합니다. 경고 메시지 "Context length exceeded. Summarizing content to fit the model context window." 후 자동 요약으로 실행을 계속합니다.
• respect_context_window=False: 완전한 컨텍스트가 필요한 정밀 작업용. 컨텍스트 한도를 초과하면 "Context length exceeded. Consider using smaller text or RAG tools from crewai_tools." 오류로 실행을 즉시 중단하고 수동 개입이 필요합니다.

선택 가이드: 큰 문서 처리·긴 대화·연구 태스크·프로토타이핑에는 True(기본), 법률·의료·코드 리뷰·금융 분석처럼 정보 손실이 용납 안 되는 정밀 작업에는 False.

에이전트와 직접 상호작용: kickoff()

agent.kickoff(...)로 에이전트와 직접 상호작용할 수 있습니다.

# Create an agent
researcher = Agent(
    role="AI Technology Researcher",
    goal="Research the latest AI developments",
    tools=[SerperDevTool()],
    verbose=True
)

# Use kickoff() to interact directly with the agent
result = researcher.kickoff("What are the latest developments in language models?")

# Access the raw response
print(result.raw)

kickoff()는 LiteAgentOutput 객체를 반환합니다: raw(원본 출력 문자열), pydantic(response_format 제공 시 파싱된 Pydantic 모델), agent_role(출력 생성 에이전트 역할), usage_metrics(토큰 사용 메트릭). Pydantic 모델을 response_format으로 제공해 구조화 출력을 얻을 수 있고, kickoff_async() 비동기 버전도 있습니다. <Note> kickoff()는 내부적으로 LiteAgent를 사용해 에이전트의 모든 설정(role, goal, backstory, tools 등)을 보존하면서 더 단순한 실행 흐름을 제공합니다. </Note>

중요한 고려사항·모범 사례

• 성능 최적화: respect_context_window: true로 토큰 한도 방지, 적절한 max_rpm 설정, 반복 태스크에 cache: true, 태스크 복잡도에 따라 max_iter·max_retry_limit 조정.
• 메모리·컨텍스트 관리: 도메인 정보에 knowledge_sources 활용, 사용자 정의 임베딩 모델 시 embedder 구성, 미세 제어에 사용자 정의 템플릿 사용.
• 고급 기능: 복잡한 태스크 전 계획·반성이 필요하면 reasoning: true, max_reasoning_attempts로 제어(None이면 무제한), 시간 민감 태스크에 inject_date: true + date_format(표준 Python datetime 형식 코드).
• 에이전트 협업: 함께 작업해야 하면 allow_delegation: true, step_callback으로 상호작용 모니터링·로깅, 목적별 LLM 분리(복잡 추론용 메인 llm, 효율적 툴 사용용 function_calling_llm).
• 모델 호환성: 시스템 메시지를 지원하지 않는 구형 모델에는 use_system_prompt: false.

트러블슈팅

1. 레이트 리밋: 적절한 max_rpm 구현, 반복 연산에 캐싱, 요청 배칭 고려.
2. 컨텍스트 창 오류: respect_context_window 활성화, 더 효율적인 프롬프트, 주기적으로 메모리 정리.
3. 코드 실행 문제: safe 모드에 Docker 설치 확인, 실행 권한 확인, 코드 샌드박스 설정 검토.
4. 메모리 문제: 지식 소스 설정 확인, 대화 이력 관리 검토.

에이전트는 특정 사용 사례에 맞게 구성될 때 가장 효과적입니다. 요구사항을 이해하고 파라미터를 그에 맞게 조정하세요.

더 알아보기

• CrewAI 크루 구성
• 에이전트 협업과 위임
• 에이전트 리즈닝
• 에이전트 캐퍼빌리티: 툴·MCP·앱·스킬·지식
• 태스크 가이드