Agno로 에이전트 구축하기

가을·2025년 11월 20일
DEVOCEAN OpenLab

DEVOCEAN OpenLab

목록 보기
1/1

DEVOCEAN OpenLab 2025 발표

1. Introduction

안녕하세요!

DEVOCEAN OpenLab 2025의 “멀티모달 기반 AI 챗봇 기술 연구 & 개발” 스터디에 참여 중인 가을입니다.

이번 포스팅에서는 최근 AI 트렌드로 주목받는 AI Agent와 Agno 프레임워크를 활용해 상담형 에이전트를 실습한 내용 공유하려 합니다.

이 글에서는 다음 내용을 다룹니다.

  • Agent란 무엇인가
  • Agno의 구조와 주요 개념
  • 간단한 Simple Agent 실습
  • Agno 기반 B tv 상담 Agent 실습

2. Agent란?

2.1. Agentic AI vs AI Agent

요즘 자주 등장하는 “에이전트(Agent)”는 단순히 모델을 호출하는 시스템이 아닙니다.

Agent는 모델이 실행 흐름을 스스로 제어하며 추론, 행동, 응답을 결정하는 자율적 AI 프로그램을 의미합니다.

구분Agentic AIAI Agent
개념모델이 능동적으로 계획·추론·행동·피드백을 수행하는 패러다임그 개념을 실제 시스템에 구현한 인스턴스
특징LLM 기반의 자율성, 도구 사용, 멀티스텝 추론특정 도메인(예: 상담, 분석, 추천)에 특화된 구조
예시OpenAI o1-preview, AutoGPT, LangGraph AgentsBtv 상담 Agent, 문서 분석 Agent 등

즉, Agent는 “지시를 수행하는 AI”가 아니라 “스스로 생각하고 실행하는 AI”라고 할 수 있습니다.

3. Agno란?

Agno는 Agent Orchestration에 특화된 Python 프레임워크입니다.

단일 에이전트부터 복수의 팀 단위 워크플로까지 모두 구성할 수 있으며, FastAPI 기반 런타임과 UI를 함께 제공합니다.

공식 문서 Link

3.1. Agno의 핵심 특징

  1. Pre-built FastAPI Runtime
    • AgentOS는 즉시 실행 가능한 FastAPI 앱 형태로, Agent, Team, Workflow를 곧바로 실행할 수 있습니다.
  2. Integrated UI
    • AgentOS UI를 통해 런타임에 직접 연결되어 시스템 테스트, 모니터링, 관리가 가능합니다.
  3. Privacy by Design
    • 모든 데이터 처리를 클라우드 내부에서 수행하여 개인 정보 보호를 보장합니다.
  4. 성능
    • 공식 벤치마크에 따르면 타 프레임워크 대비 처리 속도와 응답 일관성이 우수합니다.

4. Agno의 주요 개념

구성요소역할
Memory과거 대화를 기억하고 학습하여 반응 품질 향상
Storage세션 상태를 DB에 저장하여 상태 기반 상호작용 지원
Knowledge벡터DB 기반 도메인 지식 검색 (Agentic RAG / Search)
Reasoning응답 전 사고·분석을 수행하여 신뢰성 강화

4.1. Agent 구조

  • Model : 사고(Reason), 행동(Act), 응답(Respond) 결정
  • Instructions : 에이전트의 행동 지침
  • Tools : 외부 시스템과 상호작용하는 실행 도구

4.2. Team & Workflow

  • Team : 여러 Agent 혹은 하위 Team의 집합으로, 복잡한 문제를 분담 처리
  • Workflow : 결정적 실행 제어를 통해 일관된 자동화를 지원

5. Simple Agent 실습

위에서 배운 Agno를 활용하여 아주 간단하게 에이전트를 구축해보겠습니다.

한 개의 Python 파일만으로 기본 구조를 완성할 수 있습니다.

우선 저는 무료로 호출할 수 있는 Gemini API(2025.10.15일 기준)를 이용해서 구축했습니다.

5.1. 환경 설정

  1. .env 파일에 Gemini API 키를 등록

    GEMINI_API_KEY=your_key_here

  2. Python 코드

    from dotenv import load_dotenv
load_dotenv()  # .env 파일 로드

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.google import Gemini
from agno.os import AgentOS

# ************* 에이전트 생성 *************
agno_agent = Agent(
    name="Agno 실험 에이전트",
    model=Gemini(id="gemini-2.0-flash"),
    # 데이터베이스 추가
    db=SqliteDb(db_file="agno_os.db"),
    # 이전 대화 기록을 컨텍스트에 추가
    add_history_to_context=True,
    instructions=[
        "당신은 친절한 AI 어시스턴트입니다.",
        "한국어로 대답해주세요."
    ],
    markdown=True,
)

# ************* AgentOS 생성 *************
agent_os = AgentOS(agents=[agno_agent])
# FastAPI 앱 가져오기
app = agent_os.get_app()

# ************* AgentOS 실행 *************
if __name__ == "__main__":
    # 서버 실행: http://localhost:7777
    # AgentOS UI는 https://os.agno.com 에서 접속 가능
    agent_os.serve(app="agent_os_server:app", reload=True)

  3. Terminal 

    python main.py

이후 Agent UI에서 실시간 테스트가 가능합니다.

  1. **https://os.agno.com/** 접속

  2. Local, endpoint url, name 설정 후 Update 버튼 클릭

  3. Chat에서 실험할 수 있습니다.

    Agno에 대해 Gemini API 기반 Agent에게 물어봤을때,
    검색 툴을 연결하지않아 이상한 대답을 하는 것을 확인할 수 있습니다.

Tip.
Agno 객체는 기본적으로 OpenAI API를 사용합니다.
다른 모델(Gemini, Claude 등)을 사용하려면 반드시 명시해야 합니다.

6. B tv 상담 Agent 구축 실습

Agno는 Agnet orchestration에 특화된 Framework인 만큼, 이에 대해 성능을 확인해보려고 합니다.

6.1. 실험 구조

  • 실험 1) 단일 Agent
  • 실험 2) Team
    1. 문서 검색 Agent : PDF 내 정보 검색
    2. 기술 해설 Agent : 검색된 내용 정리
    3. 품질 검증 Agent : 답변 타당성 점검
    4. Team leader Agent

6.2. 공통 설정

Knowledge에는 ‘B tv 통합서비스 이용가이드.pdf’ 문서를 이용하여 단순 PDFReader로 읽고 임베딩하여 상담이 가능하도록 구성했습니다.

from dotenv import load_dotenv
load_dotenv()

from agno.agent import Agent
from agno.knowledge import Knowledge
from agno.vectordb.lancedb import LanceDb
from agno.knowledge.embedder.google import GeminiEmbedder
from agno.knowledge.reader.pdf_reader import PDFReader
from agno.knowledge.chunking.fixed import FixedSizeChunking
from agno.models.google import Gemini
from agno.os import AgentOS
from agno.db.sqlite import SqliteDb

# ************* LanceDB로 로컬 Vector DB 설정 *************
vector_db = LanceDb(
    table_name="service_guide",
    uri="./lancedb",
    embedder=GeminiEmbedder()
)

# ************* Knowledge 생성 및 PDF 추가 *************
knowledge = Knowledge(vector_db=vector_db)

knowledge.add_content(
            path="통합서비스_이용가이드.pdf",
            reader=PDFReader(
                chunking_strategy=FixedSizeChunking(
                    chunk_size=1000,  # 93자 → 1000자로 증가
                    overlap=200       # 청크 간 오버랩으로 맥락 유지
                )
            ),
            metadata={"type": "guide", "category": "service"}
        )

그리고 동일하게 “AI 스피커형 셋톱박스의 불빛 색 별 의미를 알려줘” 라는 질문을 입력했습니다.

해당 질문에 대한 정답페이지 아래 이미지의 왼쪽입니다.

그리고 이에 해당하는 chunck는 다음과 같습니다.

--- Chunk 3 ---
ID: cb9912d390c043c9e1fbfa7769421df2
파일명: 통합서비스_이용가이드.pdf
메타데이터: {'page': 4, 'chunk': 1, 'chunk_size': 999, 'type': 'guide', 'category': 'service'}
내용: 6 Smart 3, UHD 4 셋톱박스 윗면 뒷면 셋톱박스의 동작 상태에 따라 불빛이 들어와요. B tv 채널을 변경할 수 있어요. 상태 알림 LED 채널채널 마이크(MIC) 입력 랜 포트 HDMI 포트 USB  포트 전원 연결 포트 마이크를 연결할 수 있어요. 랜 케이블을 이용해 SK브로드밴드 인터넷을 연결해요. HDMI 케이블을 이용해 TV와 연결해요. USB 메모리를 연결할 수 있어요.(USB 2.0 , USB 3.0 ) 전원 어댑터를 연결해요. 흰색 불빛 : 나타남 B tv 시청 중일 때 초록색 불빛 : 나타남 B tv 전원이 꺼졌을 때(B tv 대기모드) 흰색 불빛 : 깜박임 B tv 전원이 켜질 때 / 시스템을 시작할 때 빨간색 불빛 : 깜박임 네트워크 오류가 발생했을 때 전원을 켜고 서비스를 시작하면 초록색과 파란색 불빛이 들어와요. “아리아”라고 말하면, 사용자의 위치에 따라 파란색 불빛이 들어와요. ※ 빔 포밍(Beam Forming) 기술을 이용해, 소리가 나는 위치를 실시간으로 인지하고, 사용자의 위치에 따라 불빛이 함께 움직여요. 사용자의 음성을 인식하는 동안에는 파란색 불빛이 좌우로  동작을 반복해요. 사용자의 요청을 처리하는 동안에는 파란색 불빛이 좌우로 크게 들어와요. 사용자의 요청에 따라 응답할 때는 파란색 불빛이 천천히 깜박거려요. 마이크가 꺼지면 “아리아”라 고 불러도 음성을 인식할 수 없어요. 주황색 불빛이 좌우로 크기가 줄어들어요. ※ 마이크를 다시 켜려면, 셋톱박스 뒷면에 있는 [마이크 OFF] 버튼을 다시 눌러 마이크를 켜 주세요. 혹은 B tv 홈 화면에서 [MY ▶ 설정 ▶ NUGU 설정 ▶ 음성인식 사용설정]을 선택한 후, ‘사용함’으로 설정을 변경해 주세요. 음량의 크기에 따라 흰색 불빛이 들어와요. 음량이 0이 되거나 ‘조용히’ 모드일  때는 중앙에 흰색 불빛이 들어와요. ※ 음량은 총 32단계로 조절할 수 있으며, 불빛의 밝기와 위치로 음량의 크기를 확인할 수 있어요. 중앙에 주황색 불빛이 들어와요. 불빛이 오랫동안        
Vector 차원: 1536

--- Chunk 4 ---
ID: a82e137ee4afd86163e02cdadf062fba
파일명: 통합서비스_이용가이드.pdf
메타데이터: {'page': 4, 'chunk': 2, 'chunk_size': 363, 'type': 'guide', 'category': 'service'}
내용:  ▶ NUGU 설정 ▶ 음성인식 사용설정]을 선택한 후, ‘사용함’으로 설정을 변경해 주세요. 음량의 크기에 따라 흰색 불빛이 들어와요. 음량이 0이 되거나 ‘조용히’ 모드일 때는 중앙에 흰색 불빛이 들어와요. ※ 음량은 총 32단계로 조절할 수 있으며, 불빛의 밝기와 위치로 음량의 크기를 확인할 수 있어요. 중앙에 주황색 불빛이 들어와요. 불빛이 오랫동안 나타나면, 고객센터로 문 의해 주세요.(고객센터 106) 서비스를 시작할 때 음성인식 기능을 사용할 때 마이크가 꺼졌을 때 음량을 조절할 때 시스템 오류가 발생했을 때 상태별 알림 안내 AI 스피커형 셋톱박스 5 ※ B tv pop 이용 고객의 경우, Smart 3 셋톱박스만 설치 가능해요.
Vector 차원: 1536

단순한 PDFReader 와 FixedSizeChunking을 이용했기 때문에,
잘 나눠지지는 않은 것을 확인할 수 있었습니다.

특히, 정답페이지의 왼쪽과 오른쪽 방면의 내용이 섞인 것을 확인할 수 있었습니다.

기본 세팅으로 Agent들의 성능을 확인하고 싶었기에 실험은 이대로 진행했습니다.

6.3. 실험 1) 단일 Agent

code

# ************* Gemini 모델로 상담사 에이전트 생성 *************
agent = Agent(
    name="통합서비스 고객지원 챗봇",
    model=Gemini(id="gemini-2.0-flash"),
    knowledge=knowledge,
    search_knowledge=True,
    db=SqliteDb(db_file="rag_chatbot.db"),
    add_history_to_context=True,
    instructions=[
        "당신은 통합서비스 고객지원 챗봇입니다.",
        "제공된 매뉴얼을 기반으로 정확하게 답변하세요.",
        "문서에 없는 내용은 추측하지 말고 정중하게 안내하세요.",
    ],
    markdown=True,
)

# ************* AgentOS로 UI 제공 *************
agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()

if __name__ == "__main__":
	agent_os.serve(app="agent_rag_chatbot:app", reload=True)

결과

chunck 분할이 제대로 안되었던 점을 감안하면, 간결히 정리되어 나오는 것을 볼 수 있습니다.

6.4. 실험 2) Team

여기서는 총 3개의 하위 Agent와 Team Learder Agent를 사용했습니다.

  1. 문서 검색 Agent : PDF 내 정보 검색
  2. 기술 해설 Agent : 검색된 내용 정리
  3. 품질 검증 Agent : 답변 타당성 점검
  4. Team Leader Agent : 통합서비스 전문 상담팀 리더(1~3을 통솔)

code

# 1. 문서 검색 전문가
search_expert = Agent(
    name="문서검색전문가",
    role="매뉴얼에서 관련 정보를 찾는 전문가",
    model=Gemini(id="gemini-2.0-flash"),
    knowledge=knowledge,
    search_knowledge=True,
    instructions=[
        "당신은 문서 검색 전문가입니다.",
        "고객 질문을 분석하여 핵심 키워드를 파악하세요.",
        "매뉴얼에서 관련된 모든 정보를 철저히 검색하세요.",
        "특히 표, 목록, 단계별 설명 등을 주의 깊게 찾으세요.",
        "찾은 정보를 구조화하여 다른 팀원에게 전달하세요.",
    ],
    markdown=True,
)
# 2. 기술 해설 전문가
technical_expert = Agent(
    name="기술해설전문가",
    role="기술 내용을 쉽게 설명하는 전문가",
    model=Gemini(id="gemini-2.0-flash"),
    knowledge=knowledge,
    search_knowledge=True,
    instructions=[
        "당신은 기술 해설 전문가입니다.",
        "검색된 기술 정보를 고객이 이해하기 쉽게 설명하세요.",
        "전문 용어는 쉬운 말로 풀어서 설명하세요.",
        "단계, 절차, 색상 등 구체적 정보는 정확히 전달하세요.",
        "예시나 비유를 활용하여 이해를 돕세요.",
    ],
    markdown=True,
)
# 3. 품질 검증 전문가
quality_checker = Agent(
    name="품질검증전문가",
    role="답변의 정확성을 검증하는 전문가",
    model=Gemini(id="gemini-2.0-flash"),
    knowledge=knowledge,
    search_knowledge=True,
    instructions=[
        "당신은 품질 검증 전문가입니다.",
        "팀원들이 제공한 답변이 문서 내용과 일치하는지 확인하세요.",
        "누락된 중요 정보가 있는지 점검하세요.",
        "최종 답변이 고객 질문에 완전히 답하는지 확인하세요.",
        "필요시 추가 검색이나 보완을 요청하세요.",
    ],
    markdown=True,
)
# ************* 상담 팀 구성 *************
support_team = Team(
    name="통합서비스 전문 상담팀",
    model=Gemini(id="gemini-2.0-flash"),  # 팀 리더 모델
    members=[search_expert, technical_expert, quality_checker],
    db=SqliteDb(db_file="rag_team.db"),
    add_history_to_context=True,
    instructions=[
        "당신은 통합서비스 고객지원팀의 리더입니다.",
        "팀원들과 협력하여 고객 질문에 정확하고 완전한 답변을 제공하세요.",
        "",
        "작업 순서:",
        "1. 문서검색전문가가 관련 정보를 찾습니다.",
        "2. 기술해설전문가가 내용을 이해하기 쉽게 정리합니다.",
        "3. 품질검증전문가가 답변을 검증하고 보완합니다.",
        "4. 최종 답변을 고객에게 친절하게 전달합니다.",
        "",
        "품질 기준:",
        "- 문서에 근거한 정확한 정보",
        "- 명확하고 이해하기 쉬운 설명",
        "- 고객 질문에 완전히 답변",
        "- 친절하고 전문적인 톤",
    ],
    markdown=True,
)
# ************* AgentOS로 UI 제공 *************
agent_os = AgentOS(teams=[support_team])
app = agent_os.get_app()

if __name__ == "__main__":
	agent_os.serve(app="agent_rag_team:app", reload=True)

결과

  1. Team내 소통

  2. 최종 응답

실험 1) 단일 Agent때의 답변과 비교했을때,

더 구체적이고 명료하게 작성된 것을 확인할 수 있었습니다.

7. 느낀 점

직접 실습해 본 결과, Agno는 다음과 같은 장점이 있었습니다.

  1. 빠르고 직관적인 Agent 구축 가능
  2. UI에서 바로 채팅 테스트 가능
  3. MCP(Multi-Context Protocol) 제공 → Cursor 등 개발 환경과 통합 용이
  4. FastAPI처럼 외부 API 연동이 쉬움
  5. JSON 형태의 응답 및 LLM 평가(LLM-as-a-Judge 등) 기능 지원

무엇보다 “에이전트 개발이 이렇게 단순해질 수 있다”는 점이 인상적이었습니다.

향후에는 멀티모달 입력과 MCP 연동 기능까지 활용해볼 계획입니다.

읽어주셔서 감사합니다.

profile
가을
안녕하세요. 2년차 머신러닝 엔지니어입니다.

1개의 댓글

comment-user-thumbnail
하늘
2025년 12월 22일

잘보고 갑니다~

답글 달기