Agno로 AI 에이전트 만들기 — 실제는 제미니와 내장 툴로 실행

출처: Dev.to

LangChain이 너무 무거워 느껴진 적이 있다면, 당신은 혼자가 아닙니다. 의존성 트리는 엄청나게 큽니다. 추상화 레이어가 쌓입니다. 어느 순간 실제로는 무엇인가 happening underneath을 잃어버립니다. 이 불편함은 많은 사람들을 더 가벼운 대안 — 프레임워크로 이끌었습니다. 그 프레임워크들은 100개의 전이 의존성을 갖지 않고도 강력한 에이전트를 구축할 수 있음을 증명합니다.

Agno의 의미와 기원

Phidata는 ‘AI 어시스턴트를 위한 파이썬 프레임워크’라는 탄탄한 평판을 구축했습니다. 2025년에 Agno로 리브랜딩되면서 설계 철학이 보다 명확하게 세 가지 아이디어에 중점을 두게 되었습니다.

모델 무관성 desde 시작. 약 70개의 LLM(오픈AI, 안트로픽, 구글, 올라마, 코히어)들이 동일한 코드 구조로 연결될 수 있습니다. 모델을 교체하고 에이전트 로직은 그대로 유지합니다.

텍스트를 기본으로 한 다중 모달. 텍스트, 이미지, 오디오, 비디오 에이전트들은 동일한 API 표면을 사용합니다. 각 모달에 대해 별도의 추상화 계층을 만들 필요가 없습니다.

다중 에이전트 오케스트레이션을 1등 citizens로. Team 클래스가 기본 제공됩니다. coordinate, route, collaborate 모드 간 전환은 파라미터 하나만 변경하면 됩니다.

그 내용을 읽으면서我想知道: “이것은 LangChain과 어떻게 다른가?” 실제 코드를 작성하면서 답을 얻었습니다. Agno는 상속보다 구성을 선호합니다. 한 에이전트를 설정하는 데 약 6줄 정도만 필요합니다. boilerplate를 처리해야 할 양이 훨씬 적습니다.

설치: 의존성 지옥 없음

pip install agno google-genai ddgs wikipedia

Enter fullscreen mode
Exit fullscreen mode

agno 패키지는 핵심만 설치합니다. 도구들은 자체 추가 의존성을 필요로 합니다 — wikipedia는 위키피디아 도구용, google-genai는 제미니용입니다. 이 지연 로드 방식은 기본 설치를 깔끔하게 유지합니다.

$ python3  -c "import agno; print(agno.__version__)"
2.6.17

Enter fullscreen mode
Exit fullscreen mode

저는 프로젝트 .env에 있는 Gemini API 키를 사용했습니다. Agno는 GOOGLE_API_KEY 또는 GEMINI_API_KEY 중 하나에서 자동으로 Gemini 클라이언트를 초기화합니다. 둘 다 설정되어 있으면 GOOGLE_API_KEY를 사용하고 콘솔에 경고를 출력합니다. 큰 문제는 아니지만 코드 내에서 쉽게 억제할 수 없습니다.

첫 번째 에이전트: 계산기 도구

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.calculator import CalculatorTools
agent = Agent(
    model=Gemini(id="gemini-2.5-flash"),
    tools=[CalculatorTools()],
    description="A math helper agent",
)
response = agent.run("What is 2^10 + 3^5? Please use the calculator.")
print(response.content)

Enter fullscreen mode
Exit fullscreen mode

Output:

2^10 is 1024 and 3^5 is 243. Adding them gives 1267.
⏱ 8.98s

Enter fullscreen mode
Exit fullscreen mode

수학은 맞습니다: 1024 + 243 = 1267. 에이전트는 추측 대신 Calculator 도구를 호출했습니다. 9초 지연에는 Gemini API 라운드트립과 도구 호출 오버헤드가 포함됩니다.

Trap #1: show_tool_calls이 사라졌습니다. 오래된 Agno 튜토리얼에서는 show_tool_calls=True를 사용합니다. v2.6.17에서는 TypeError: Agent.__init__() got an unexpected keyword argument 'show_tool_calls'가 발생합니다. verbose한 출력을 원하면 debug_mode=True를 대신 사용하세요.

Trap #2: gemini-2.0-flash 모델은 더 이상 사용되지 않습니다. 404 오류가 발생합니다. 대신 gemini-2.5-flash를 사용하세요. 실제 사용 가능한 모델 ID를 Google 문서에서 확인한 뒤 하드코딩하지 마세요.

위키피디아 에이전트: 자동 검색 재시도

from agno.tools.wikipedia import WikipediaTools
agent = Agent(
    model=Gemini(id="gemini-2.5-flash"),
    tools=[WikipediaTools()],
)
response = agent.run(
     "What is the 'attention mechanism' in neural networks? 2 sentences only."
) 

Enter fullscreen mode
Exit fullscreen mode

Execution log:

INFO Searching wikipedia for: attention mechanism neural networks
ERROR Error searching Wikipedia for  'attention mechanism neural networks':
      Page id "attention mechanism neural network" does not match any pages.
INFO Searching wikipedia for: attention (machine learning)
⏱ 9.98s

Enter fullscreen mode
Exit fullscreen mode

재미있는 점은 첫 번째 검색이 실패했고, 에이전트가 자동으로 쿼리를 (attention (machine learning)) 로 재구성하여 다시 시도했다는 것입니다. 추가 코드 없이도 동작합니다. Agno는 내부적으로 ReAct 루프(계획, 행동, 관찰, 조정)를 실행합니다. 도구 실패는 원활하게 처리됩니다.

Smolagents의 코드 실행 방식(아래 파이썬 AI 에이전트 라이브러리 비교 포스트)와 대비하면 Agno는 코드 생성보다 도구 조합에 더 집중합니다. 어느 쪽이든 절대적으로 더 나은 것은 아니며, 무엇을 구축하느냐에 따라 달라집니다.

구조화된 출력: output_schema 사용, output_model이 아니라

API에서 가장 혼동스러운 네이밍 중 하나입니다. output_model이라는 파라미터가 있습니다. 자연스럽게 생각하시겠지만, ” 여기를 Pydantic 모델로 두세요.” 라고 생각할 수 있지만,那是 잘못된 생각이에요.

# This fails
agent = Agent(
    model=Gemini(id="gemini-2.5-flash"),
    output_model=DeveloperProfile,   # ← WRONG
)

output_model은 LLM 모델 인스턴스(또는 문자열 모델 ID)를 기대합니다. Pydantic 구조화된 출력을 원하면 output_schema를 사용하세요.

from pydantic import BaseModel
from typing import List
class Skill(BaseModel):
    name: str
    level: str
    year_since: int
class DeveloperProfile(BaseModel):
    name: str
    skills: List[Skill]
    summary: str
agent = Agent(
    model=Gemini(id="gemini-2.5-flash"),
    output_schema=DeveloperProfile,   # ← CORRECT
)
response = agent.run(
     "Create a developer profile for 'Kim Jangwook', a Korean developer specializing in Claude Code, MCP, Python, TypeScript."
) 
print(type(response.content))    # 
print(response.content.name)     # Kim Jangwook

Enter fullscreen mode
Exit fullscreen mode

실제 출력: … 4초 지연(계산기 에이전트의 9초 대비)은 도구 호출 라운드트립이 없다는 점에서 비롯됩니다. 이는 PydanticAI의 output_type 파라미터와 정신적으로 유사하지만, 네이밍이 다릅니다. 프레임워크를 옮길 때는 각기 다른 어휘를 기억해야 하며, 이것이累积되는 마찰이 됩니다.

다중 에이전트 팀: members=, Not agents=

from agno.team import Team
researcher = Agent(
    name="Researcher",
    model=Gemini(id="gemini-2.5-flash"),
    tools=[WikipediaTools()],
    role="researcher",
)
calculator = Agent(
    name="Calculator",
    model=Gemini(id="gemini-2.5-flash"),
    tools=[CalculatorTools()],
    role="calculator",
)
team = Team(
    members=[re

members= 파라미터는 팀에 포함될 에이전트 리스트를 지정합니다. agents=가 아닙니다.