에이전트 (Agents)

출처: Haystack 공식 문서 – Agents (버전 3.0)

이번엔 Haystack에서 AI 에이전트(Agent) 를 만드는 방법을 다뤄볼게요. 에이전트는 여러 Haystack 컴포넌트를 이용해 정보를 찾고, 응답을 만들고, 실제로 행동까지 취하는 시스템이에요.

에이전트가 뭘 할 수 있나요

에이전트를 한마디로 설명하면 스스로 판단해서 일을 해내는 시스템이에요. 챗봇이 단순히 대답을 주고받는 것과 달리, 에이전트는 목표를 정하고 적절한 도구를 고르고 작업을 직접 실행해요. 대략 네 가지 일을 할 수 있어요.

사용자 입력을 이해해요. 텍스트는 물론 이미지, 오디오 같은 다양한 쿼리를 받아들여요.
필요한 정보를 검색해요. 문서나 구조화된 데이터에서 찾아와요.
지능적인 응답을 생성해요. OpenAI나 Hugging Face 같은 LLM을 써서요.
행동을 취해요. API를 호출하거나, 실시간 데이터를 가져오거나, 함수를 실행하는 식으로요.

에이전트를 이루는 네 가지 요소

에이전트는 학습을 시작할 때 역할과 목표를 정하는 프롬프트(prompt)에서 출발해요. 그리고 나서 네 가지 요소가 서로 짜여서 돌아가요.

LLM이 뇌(Brain) 역할을 해요. 맥락을 이해하고 자연어를 처리하는 중심 지능이에요.
도구(Tools)로 상호작용해요. 외부 도구, API, 데이터베이스에 연결해 정보를 모으고 행동을 취해요.
메모리(Memory)로 맥락을 유지해요. 단기 메모리는 대화를 따라가고, 장기 메모리는 나중에 쓸 지식을 저장해요.
추론과 계획(Reasoning and Planning) 을 해요. 복잡한 문제를 쪼개고 단계별 계획을 세우다가, 새 데이터와 피드백에 따라 방향을 바꿔요.

이 요소들이 모이면 에이전트는 추론과 행동의 루프를 돌아가며 계획을 다듬어요. 예를 들어 고객 서비스 에이전트는 데이터베이스를 보고 질문에 답하다가, 답이 없으면 실시간 데이터를 가져와 요약해서 응답해요. 코딩 어시스턴트는 프로젝트 요구사항을 이해하고 해결책을 제안한 뒤 코드를 작성하고요.

Haystack의 Agent 컴포넌트

Haystack에는 이 도구 호출 루프(tool-calling loop) 전체를 관리하는 내장 Agent 컴포넌트가 있어요. 이 컴포넌트가 뭘 하는지 먼저 감을 잡아볼게요.

상태 관리(State management): 도구끼리 타입화된 데이터를 공유하고, 반복마다 결과를 쌓아요. state_schema에 선언한 키는 결과 딕셔너리에서 messages, last_message와 함께 반환돼요. 자세한 건 State 문서를 봐요.
스트리밍(Streaming): streaming_callback으로 토큰 단위 출력을 실시간으로 흘려보내요.
Human-in-the-loop: 실제 실행 전에 도구 호출을 사람이 검토하도록 가로챌 수 있어요. Human in the Loop 문서를 참고해요.
멀티 에이전트 시스템: Agent를 ComponentTool로 감싸면 조정자(coordinator)/전문가(specialist) 구조를 만들 수 있어요. Multi-Agent Systems에서 다뤄요.
MCP 서버 노출: Hayhooks를 쓰면 에이전트를 MCP 서버로 노출해, Claude Desktop이나 Cursor 같은 MCP 호환 클라이언트 어디서든 호출할 수 있어요.
멀티모달 입력: ChatMessage 콘텐츠 부분에 ImageContent를 넣어 이미지를 텍스트와 함께 전달하거나, 도구에서 ImageContent를 반환해 동적 이미지 분석을 할 수 있어요. gpt-5나 gemini-2.5-flash 같은 비전(vision) 지원 모델이 필요해요. Multimodal Inputs를 봐요.

쉽게 말하면, Agent는 LLM을 호출하고 → 도구를 실행하고 → 상태를 갱신하고 → 종료 조건(stopping condition)이 채워질 때까지 이 과정을 반복해요.

도구(Tool)를 만드는 여러 방법

에이전트가 실제로 뭔가를 하려면 도구가 필요하죠. State가 도구 사이 데이터 공유를 담당한다면, 도구 자체를 만드는 방법도 다양해요.

Tool 클래스 / @tool 데코레이터 – Python 함수에서 도구를 정의해요. @tool 데코레이터는 함수 이름과 docstring을 자동으로 쓰고, Tool 클래스는 이름·설명·스키마를 완전히 제어할 수 있어요.
ComponentTool – 어떤 Haystack 컴포넌트든 호출 가능한 도구로 감싸요.
PipelineTool – 파이프라인 전체를 하나의 호출 가능한 도구로 감싸요.
MCPTool / MCPToolset – Model Context Protocol(MCP) 서버에 연결해 외부 도구를 불러와요.
Toolset – 여러 도구를 하나의 단위로 묶어서 Agent나 Generator에 전달해요.
SearchableToolset – 큰 도구 모음에서 키워드 기반 도구 검색을 가능하게 해요. 덕분에 LLM은 매 단계에서 필요한 도구만 볼 수 있어요.

실제로 도구 호출 에이전트 만들기

Agent 컴포넌트로 도구 호출 에이전트를 만들어볼게요. 아래 예시를 돌리려면 환경 변수 OPENAI_API_KEY와 SERPERDEV_API_KEY가 설정되어 있어야 해요.

이 페이지의 예시는 serperdev-haystack 패키지로 옮겨진 SerperDev 웹 검색 컴포넌트를 쓰고 있어요. 예시를 실행하려면 패키지를 설치해야 해요.

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)

코드에서 핵심은 이 부분이에요. ComponentTool로 감싼 SerperDev 웹 검색을 web_search라는 이름의 도구로 만들어 Agent의 tools에 넘겨줬어요. 시스템 프롬프트가 "현재 정보를 물어보면 웹 검색 도구를 쓰라"고 안내하니까, 에이전트는 Berlin 날씨 질문을 받자마자 스스로 web_search를 호출해요.

실행하면 이런 식의 결과가 나와요.

>>> 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).

에이전트가 스스로 도구를 골라 실행하는 흐름이 눈에 보이죠. 처음엔 Agent 컴포넌트 하나로 시작해도 좋아요. 나중에 상태 관리나 멀티 에이전트 구조가 필요해지는 순간, 위에 언급한 문서들을 따라 확장해 나가면 돼요.