에이전트

에이전트 (Agents)

이 페이지는 정보를 검색하고 응답을 생성하며 다양한 Haystack 컴포넌트를 사용해 작업을 수행하는 AI 에이전트를 Haystack에서 만드는 방법을 설명해요.

출처: 공식문서

AI 에이전트란?

AI 에이전트는 다음과 같은 일을 할 수 있는 시스템이에요:

  • 사용자 입력을 이해한다 (텍스트, 이미지, 오디오, 기타 쿼리)
  • 관련 정보를 검색한다 (문서 또는 구조화된 데이터)
  • 지능형 응답을 생성한다 (OpenAI나 Hugging Face 모델 같은 LLM 사용)
  • 작업을 수행한다 (API 호출, 실시간 데이터 가져오기, 함수 실행)

AI 에이전트는 대규모 언어 모델(LLM)로 의사결정을 하고 복잡한 작업을 해결하는 자율 시스템이에요. 도구(tools), 메모리(memory), 추론(reasoning)을 이용해 환경과 상호작용해요. AI 에이전트는 단순한 챗봇 그 이상이에요. 능동적으로 계획하고, 올바른 도구를 고르고, 목표를 달성하기 위해 작업을 실행해요. 전통적인 소프트웨어와 달리 새로운 정보에 적응하고 필요에 따라 과정을 개선해요.

  1. LLM은 두뇌(Brain) : 에이전트의 핵심은 LLM이에요. 문맥을 이해하고 자연어를 처리하는 중앙 지능 시스템 역할을 해요.
  2. 상호작용을 위한 도구(Tools) : 에이전트는 외부 도구, API, 데이터베이스에 연결해 정보를 모으고 행동해요.
  3. 문맥을 위한 메모리(Memory) : 단기 메모리는 대화를 추적하고, 장기 메모리는 향후 상호작용을 위한 지식을 저장해요.
  4. 추론과 계획(Reasoning and Planning) : 에이전트는 복잡한 문제를 분해하고 단계별 행동 계획을 세우며, 새 데이터와 피드백에 따라 적응해요.

AI 에이전트는 역할과 목표를 정의하는 프롬프트에서 시작해요. 언제 도구를 쓸지 결정하고, 데이터를 모으며, 추론과 행동의 루프를 통해 접근 방식을 다듬어요. 예를 들어 고객 서비스 에이전트는 데이터베이스로 질문에 답하다가 답이 없으면 실시간 데이터를 가져와 요약하고 응답해요. 코딩 어시스턴트는 프로젝트 요구사항을 이해하고 해결책을 제안하며 코드를 작성해요.

핵심 컴포넌트

Agent 컴포넌트

Haystack에는 전체 도구 호출 루프를 관리하는 내장 Agent 컴포넌트가 있어요. LLM을 호출하고 도구를 호출하며 상태를 업데이트하고 중지 조건이 충족될 때까지 계속해요. 주요 기능은 다음과 같아요:

  • 상태 관리 : state_schema로 도구 간에 타입화된 데이터를 공유하고 반복 간 결과를 누적하며 결과 dict에 노출해요. State 참고.
  • 스트리밍 : streaming_callback으로 토큰 단위 출력을 스트리밍해요.
  • 인간 개입(Human-in-the-loop) : 실행 전에 도구 호출을 가로채 인간 검토를 요청해요. Human in the Loop 참고.
  • 멀티 에이전트 시스템 : Agent를 AgentTool로 감싸 코디네이터/전문가 구조를 만들 수 있어요. Multi-Agent Systems 참고.
  • MCP 서버 노출 : Hayhooks를 사용해 에이전트를 MCP 서버로 노출하면, Claude Desktop이나 Cursor 같은 MCP 호환 클라이언트 어디서든 호출할 수 있어요.
  • 멀티모달 입력 : ChatMessage 콘텐츠 파츠에 ImageContent로 이미지를 텍스트와 함께 전달하거나, 도구에서 ImageContent를 반환해 동적 이미지 분석을 할 수 있어요. gpt-5나 gemini-2.5-flash 같은 비전 지원 모델이 필요해요. Multimodal Inputs 참고.

시작하려면 Agent 문서나 아래 예시를 확인하세요.

State

State는 도구 간 데이터 공유와 여러 도구 호출에 걸친 결과 누적을 위한 Haystack 내장 메커니즘이에요. Agent에 state_schema를 정의하면, 그곳에 선언된 키는 에이전트 결과 dict의 messages와 last_message와 함께 반환돼요.

도구 (Tools)

Haystack은 도구를 만들고 관리하는 여러 방법을 제공해요:

  • Tool 클래스 / @tool 데코레이터 — 파이썬 함수에서 도구를 정의해요. @tool 데코레이터는 함수 이름과 docstring을 자동 사용하고, Tool 클래스는 이름·설명·스키마를 완전히 제어해요.
  • ComponentTool — 어떤 Haystack 컴포넌트든 호출 가능한 도구로 감싸요.
  • PipelineTool — 전체 Haystack 파이프라인을 호출 가능한 도구로 감싸요.
  • AgentTool — Agent를 호출 가능한 도구로 감싸, 다른 Agent가 위임할 수 있게 해요.
  • MCPTool / MCPToolset — Model Context Protocol(MCP) 서버에 연결해 외부 도구를 로드해요.
  • Toolset — 여러 도구를 하나의 단위로 묶어 Agent나 Generator에 전달해요.
  • SearchableToolset — 대규모 카탈로그에서 키워드 기반 도구 검색을 가능하게 해, LLM이 각 단계에서 관련 도구만 보도록 해요.

예시

도구 호출 에이전트 (Tool-Calling Agent)

Agent 컴포넌트로 도구 호출 에이전트를 만들어 볼게요. 이 예시는 OPENAI_API_KEY와 SERPERDEV_API_KEY를 환경 변수로 설정해야 해요:

export OPENAI_API_KEY=<your-openai-key>
export SERPERDEV_API_KEY=<your-serperdev-key>

이 페이지의 예시들은 serperdev-haystack 패키지로 이동한 SerperDev 웹 검색 컴포넌트를 사용해요. 예시를 실행하려면 설치하세요:

pip install serperdev-haystack

from haystack.components.agents import Agent
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.generators.utils import print_streaming_chunk
from haystack_integrations.components.websearch.serperdev import SerperDevWebSearch
from haystack.dataclasses import ChatMessage
from haystack.tools import ComponentTool

# 웹 검색 컴포넌트를 도구로 감싼다
web_tool = ComponentTool(
    component=SerperDevWebSearch(top_k=3),
    name="web_search",
    description="Search the web for current information like weather, news, or facts.",
)

tool_calling_agent = Agent(
    chat_generator=OpenAIChatGenerator(model="gpt-5.4-nano"),
    system_prompt=(
        "You're a helpful agent. When asked about current information like weather, news, or facts, "
        "use the web_search tool to find the information and then summarize the findings."
    ),
    tools=[web_tool],
    streaming_callback=print_streaming_chunk,
)

result = tool_calling_agent.run(
    messages=[ChatMessage.from_user("How is the weather in Berlin?")],
)
print(result["last_message"].text)

실행 결과는 대략 이렇게 나와요:

The current weather in Berlin is approximately 60°F. The forecast for today includes clouds in the morning with some sunshine later. The high temperature is expected to be around 65°F, and the low tonight will drop to 40°F.

- **Morning**: 49°F
- **Afternoon**: 57°F
- **Evening**: 47°F
- **Overnight**: 39°F

For more details, you can check the full forecasts on [AccuWeather](https://www.accuweather.com/en/de/berlin/10178/current-weather/178087) or [Weather.com](https://weather.com/weather/today/l/5ca23443513a0fdc1d37ae2ffaf5586162c6fe592a66acc9320a0d0536be1bb9).

더 알아보기 (Learn more)