AI 에이전트를 제대로 만드는 5단계 설계법과 코드 예시
인공지능 시대가 도래하면서 AI 에이전트(agent)의 개념도 빠르게 진화하고 있습니다.
단순히 프롬프트만 연결하던 시절을 지나, 이제는 도구(tool)를 사용하고, 기억(memory)을 갖추고, 논리적 사고(reasoning)까지 가능하게 된 다양한 수준의 AI 시스템이 개발되고 있습니다.
하지만, 실제로 많은 개발자들이 에이전트를 만들면서 흔히 저지르는 실수가 있습니다. 바로 “프롬프트 체인”을 에이전트로 착각하는 것입니다.
작동은 하는 것처럼 보여도 실상은 상태도 없고, 기억도 없으며, 복잡한 판단을 할 수 없는, 단지 프롬프트의 반복일 뿐입니다.
이 글에서는 AI 에이전트 설계를 총 5단계 난이도로 나누고, 각 단계마다 실제 코드 예시와 함께 실용적인 설명을 제공합니다.
여러분이 이제 막 에이전트 구축을 시작했든, 복잡한 업무 자동화를 구현하고 싶든 상관없이, 이 가이드를 통해 시행착오를 줄이고 진짜 작동하는 에이전트를 만들 수 있습니다.
특히 Agno 프레임워크를 활용해 각 단계별 구현 방식을 설명하므로, 실무에 바로 활용할 수 있는 구조를 익힐 수 있습니다.
아래는 본문에서 다룰 에이전트 설계 5단계입니다.
- 단계 1: 도구와 명령을 사용하는 에이전트
- 단계 2: 지식과 기억을 갖춘 에이전트
- 단계 3: 장기 기억과 추론을 할 수 있는 에이전트
- 단계 4: 협업이 가능한 다중 에이전트 팀
- 단계 5: 인프라 수준의 비동기 시스템형 에이전트
각 단계마다 구현 방식은 물론이고, 실무에서 겪게 될 문제들과 그 해결책까지 제시합니다.
에이전트 설계 단계 1. 도구와 명령을 사용하는 에이전트
가장 기본적인 형태의 에이전트는 도구를 사용할 수 있고, 명령에 따라 행동하는 구조입니다.
이 단계의 에이전트는 LLM + Tool 구조로, 일반적인 자동화에 충분한 기능을 제공합니다.
예를 들어 웹 검색, API 호출, 간단한 계산 등을 자동으로 처리할 수 있습니다.
이때 중요한 점은 “명령에 기반한 루프 구조”를 명확히 설계하는 것입니다. 사용자가 어떤 요청을 했는지에 따라 적절한 도구를 호출하고, 결과를 재가공해 제공해야 합니다.
예시 코드:
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools
agno_assist = Agent(
name="Agno AGI",
model=OpenAIChat(id="gpt-4.1"),
description="웹 정보를 수집하고 요약해주는 에이전트",
instructions="Agno에 대해 검색하라.",
tools=[DuckDuckGoTools()],
add_datetime_to_instructions=True,
markdown=True,
)
agno_assist.print_response("Agno란 무엇인가?", stream=True)
이런 구조만으로도 고객 서비스 챗봇, 뉴스 요약기, 실시간 정보 제공 봇 등을 만들 수 있습니다.
에이전트 설계 단계 2. 지식과 기억을 갖춘 에이전트
단순한 도구 호출만으로는 복잡한 문제를 해결하기 어렵습니다.
특히 에이전트가 “무엇을 알고 있는지” 관리할 수 없다면, 항상 동일한 질문에 대해 처음부터 검색을 반복하게 됩니다. 따라서 이 단계에서는 ‘지식 검색(RAG)’과 ‘기억 저장’을 도입합니다.
- 지식 검색(RAG): Agent가 문서를 벡터로 임베딩하고, 필요한 정보를 하이브리드 방식(텍스트 + 의미 기반)으로 검색합니다.
- 기억 저장: SQLite나 NoSQL을 사용하여 대화 히스토리를 저장하면, 에이전트가 대화의 흐름을 기억할 수 있습니다.
예시 코드:
from agno.knowledge import UrlKnowledge
from agno.storage import SqliteStorage
from agno.vector_db import LanceDb, SearchType
from agno.embedder import OpenAIEmbedder
from agno.reranker import CohereReranker
knowledge_base = UrlKnowledge(
urls=["<https://docs.agno.com/introduction.md>"],
vector_db=LanceDb(
uri="tmp/lancedb",
table_name="agno_docs",
search_type=SearchType.hybrid,
embedder=OpenAIEmbedder(id="text-embedding-3-small"),
reranker=CohereReranker(model="rerank-multilingual-v3.0"),
),
)
storage = SqliteStorage(table_name="agent_sessions", db_file="tmp/agent.db")
agno_assist = Agent(
name="Agno AGI",
model=OpenAIChat(id="gpt-4.1"),
description="Agno 문서에 대한 정보를 제공하는 에이전트",
instructions="문서를 기반으로 답변하라.",
tools=[DuckDuckGoTools()],
knowledge=knowledge_base,
storage=storage,
add_history_to_messages=True,
num_history_runs=3,
markdown=True,
)
이 방식은 Q&A 시스템, 매뉴얼 봇, 교육용 튜터 등에 적합합니다.
에이전트 설계 단계 3. 장기 기억과 추론 기능을 갖춘 에이전트
에이전트가 더 똑똑해지려면 “과거의 상황을 기억하고”, “논리적으로 추론할 수 있는 능력”이 필요합니다.
이를 통해 사용자의 선호도, 실패 경험 등을 기억하고 더 나은 결과를 도출해낼 수 있습니다.
- 장기 기억: 사용자별 정보를 장기 저장하고, 상황에 따라 불러와 활용합니다.
- 추론(reasoning): 문제를 단계적으로 분석하고, 계획을 세워 다단계 실행이 가능합니다.
예시 코드:
from agno.memory import Memory, SqliteMemoryDb
from agno.tools.reasoning import ReasoningTools
memory = Memory(
model=OpenAIChat(id="gpt-4.1"),
db=SqliteMemoryDb(table_name="user_memories", db_file="tmp/agent.db"),
delete_memories=False,
clear_memories=False,
)
agno_assist = Agent(
name="Agno AGI",
model=OpenAIChat(id="gpt-4.1"),
user_id="ava",
description="사용자의 취향과 패턴을 기억하는 맞춤형 에이전트",
instructions="대화를 항상 기억하고, 이전 문맥에 따라 대응하라.",
tools=[DuckDuckGoTools(), ReasoningTools(add_instructions=True)],
memory=memory,
enable_agentic_memory=True,
)
사용자와의 장기적 상호작용이 필요한 개인 비서, 커스터마이징 챗봇 등에 활용할 수 있습니다.
에이전트 설계 단계 4. 다중 에이전트 팀
복잡한 업무를 처리하기 위해서는 하나의 에이전트만으로는 부족할 수 있습니다.
이때 다중 에이전트를 각각 역할 분담하여 팀으로 구성할 수 있습니다.
예를 들어 웹 검색 담당, 데이터 분석 담당 등으로 역할을 나눌 수 있습니다.
예시 코드:
from agno.team import Team
from agno.tools.finance import YFinanceTools
web_agent = Agent(
name="Web Search Agent",
role="웹 검색 담당",
model=OpenAIChat(id="gpt-4o-mini"),
tools=[DuckDuckGoTools()],
instructions="항상 출처를 명시하라.",
)
finance_agent = Agent(
name="Finance Agent",
role="재무 분석 담당",
model=OpenAIChat(id="gpt-4o-mini"),
tools=[YFinanceTools()],
instructions="정확한 데이터를 표 형식으로 제공하라.",
)
team_leader = Team(
name="Finance Team Leader",
mode="coordinate",
model=OpenAIChat(id="gpt-4o"),
members=[web_agent, finance_agent],
tools=[ReasoningTools(add_instructions=True)],
instructions="최종 결과만 출력하라.",
show_members_responses=True,
enable_agentic_context=True,
add_datetime_to_instructions=True,
)
이런 구조는 리서치 자동화, 뉴스 분석, 시장 보고서 생성 등에 활용됩니다.
에이전트 설계 단계 5. 시스템형 에이전트
가장 진보된 형태는 ‘Agentic System’입니다.
이 시스템은 단순한 기능이 아니라 전체 API 서비스처럼 동작하며, 비동기 요청을 처리하고 실시간으로 결과를 스트리밍합니다.
여기에는 상태 유지, 백그라운드 작업 처리, WebSocket 스트리밍 등 복잡한 인프라 설계가 필요합니다.
실시간 알림 시스템, 복합 워크플로우 관리 시스템, SaaS 서비스 등에 주로 활용됩니다.
마무리하며: 성공적인 에이전트 구축을 위한 조언
에이전트를 구축하는 데 있어 가장 중요한 것은 “기초 설계”입니다. 최신 기술을 따라가기보다, 명확한 경계 설정, 신뢰할 수 있는 기억, 안정적인 추론 시스템이 우선되어야 합니다.
다단계 구조를 서서히 도입하고, 필요에 따라 확장한다면, 단지 멋진 데모가 아닌 실제 작동하는 시스템을 만들 수 있습니다.
FAQ
Q1. 에이전트와 프롬프트 체인의 차이점은 무엇인가요?
A. 프롬프트 체인은 정해진 입력-출력 구조의 연속으로, 실질적인 상태(state)나 기억(memory)을 갖지 못합니다. 반면 에이전트는 내부 상태를 유지하고, 사용자와의 상호작용 맥락을 기억하며, 도구를 사용하거나 논리적 추론까지 수행할 수 있는 복합 구조입니다. 즉, 프롬프트 체인은 단기적 명령 실행이고, 에이전트는 지속적 의사결정과 학습을 수행하는 독립적인 지능 구조입니다.
Q2. 기억 기능은 어디에 저장되나요?
A. 기억(memory)은 주로 로컬 SQLite 데이터베이스나 클라우드 기반 벡터 데이터베이스에 저장됩니다. 예를 들어 SqliteStorage나 LanceDB, Weaviate, Pinecone 등이 사용될 수 있으며, 저장되는 정보는 사용자 ID, 대화 내용, 이전 행동 기록 등이 포함됩니다. 이를 통해 에이전트는 장기적으로 사용자 선호도나 반복 질문을 인식할 수 있습니다.
Q3. RAG 방식이란 무엇인가요?
A. RAG(Retrieval-Augmented Generation)는 LLM에 실시간 검색 능력을 결합한 방식입니다.
에이전트는 저장된 문서에서 관련 내용을 벡터 검색(semantic search)한 후, 해당 정보를 기반으로 답변을 생성합니다.
이 방식은 LLM의 한계를 극복하고, 최신 데이터나 문서 기반 정보까지 반영할 수 있는 장점이 있습니다.
Q4. 에이전트가 자신을 개선할 수 있나요?
A. 네, 가능합니다. 특히 장기 기억과 피드백 수집 시스템을 갖춘 에이전트는 과거 대화 및 사용자의 반응을 바탕으로 행동 방식을 조정할 수 있습니다.
이는 ‘자기 개선(Self-Improving Agents)’의 기초이며, 학습 기반으로 작동하는 시스템에서는 정책(policy)을 강화학습이나 규칙 기반으로 조정하기도 합니다.
Q5. 다중 에이전트는 어떻게 협업하나요?
A. 다중 에이전트는 Team 구조로 구성되며, 각각의 에이전트가 역할에 따라 특정 기능을 담당합니다.
예를 들어, 정보 검색 에이전트, 재무 분석 에이전트, 요약 에이전트 등으로 나뉘고, 이들을 조정하는 팀 리더(agent leader)가 전체 흐름을 관리합니다.
실행 모드로는 coordinate, route, collaborate 방식이 있으며, 각기 다른 작업을 효율적으로 수행하게 해줍니다.
Q6. 비동기 시스템에서는 어떤 기술이 필요한가요?
A. 에이전트를 비동기 시스템으로 운영하려면 요청 상태 관리, 백엔드 큐 처리(Redis, Celery 등), 실시간 스트리밍(WebSocket, Server-Sent Events) 등의 인프라 기술이 필요합니다.
또한 사용자의 요청을 트래킹하고 중단/재개할 수 있도록 작업 ID와 상태 저장 로직도 포함해야 합니다. 안정성과 확장성을 고려한 백엔드 설계가 핵심입니다.
Q7. 에이전트를 제품화할 때 주의할 점은?
A. 제품화 시에는 기술 구현보다 사용자의 기대치를 조절하고, 예외 상황에서의 대응 로직을 충분히 준비해야 합니다. 예를 들어, 검색 실패 시 대체 전략, 결과 지연 시 사용자 피드백, 정보의 정확성 검증 등의 로직이 필요합니다. 또한 데이터 보안, API 사용량 제한, 시스템 확장성 등도 제품화에 있어 필수 고려 요소입니다.
Q8. Agno 프레임워크는 어떤 특징이 있나요?
A. Agno 프레임워크는 에이전트 설계에 필요한 거의 모든 구성 요소를 모듈화하여 제공합니다. 도구 연결, 지식 검색(RAG), 기억 저장, 논리적 추론, 다중 에이전트 팀 구성 등 다양한 기능을 손쉽게 통합할 수 있으며, 실행 모드나 구성 요소를 커스터마이징할 수 있는 유연성이 뛰어납니다.
또한 OpenAI, Cohere, Claude 등 다양한 모델과도 호환됩니다.
