Agno 에이전트 만들기(Building Agents)

효과적인 에이전트를 만들 때는 단순하게 시작하는 게 핵심이에요. 모델·도구·지침만으로 시작하고, 동작이 확인되면 기능을 하나씩 추가하는 방식이에요. 아래는 HackerNews 도구를 가진 가장 단순한 에이전트예요.

출처: Agno 에이전트 만들기 공식 문서

from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    instructions="Write a report on the topic. Output only the report.",
    markdown=True,
)
agent.print_response("Trending startups and products.", stream=True)

model로 어떤 모델을 쓸지, tools로 어떤 도구를 줄지, instructions로 어떻게 행동할지를 정해요.

실행 전 준비

Python 가상환경을 만들고 agno와 anthropic을 설치한 뒤 ANTHROPIC_API_KEY를 설정해요.

uv pip install -U agno anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"
python hackernews_agent.py

Windows PowerShell에서는 $Env:ANTHROPIC_API_KEY="your-anthropic-api-key"로 설정해요.

에이전트 실행하기

개발 중에는 Agent.print_response()를 쓰면 터미널에 읽기 좋은 형태로 응답이 출력돼요. 프로덕션에는 Agent.run()이나 Agent.arun()을 사용해요.

from typing import Iterator
from agno.agent import Agent, RunOutputEvent, RunEvent
from agno.models.anthropic import Claude
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-5"),
    tools=[HackerNewsTools()],
    instructions="Write a report on the topic. Output only the report.",
    markdown=True,
)

# Stream the response
stream: Iterator[RunOutputEvent] = agent.run("Trending products", stream=True)
for chunk in stream:
    if chunk.event == RunEvent.run_content and chunk.content:
        print(chunk.content)

run()은 RunOutputEvent 스트림을 돌려주고, RunEvent.run_content 이벤트의 content만 골라 출력할 수 있어요.

콜러블 팩토리(Callable Factories)

tools나 knowledge에 정적 리스트 대신 함수를 넘길 수도 있어요. 팩토리는 각 실행마다 해석되며, 캐싱이 켜져 있으면 캐시된 결과를 사용해요. 이렇게 하면 사용자나 세션에 따라 도구·지식 베이스를 다르게 만들 수 있어요.

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.run import RunContext
from agno.tools.duckduckgo import DuckDuckGoTools
from agno.tools.yfinance import YFinanceTools


def get_tools(run_context: RunContext):
    role = (run_context.session_state or {}).get("role", "general")
    if role == "finance":
        return [YFinanceTools()]
    return [DuckDuckGoTools()]


agent = Agent(
    model=OpenAIResponses(id="gpt-5-mini"),
    tools=get_tools,
    cache_callables=False,
)

agent.print_response("AAPL stock price?", session_state={"role": "finance"}, stream=True)
agent.print_response("Latest AI news?", session_state={"role": "general"}, stream=True)

run_context.session_state의 role 값에 따라 도구를 다르게 돌려줘요. cache_callables=False라 세션 상태가 바뀔 때마다 팩토리를 다시 평가해요.

이 예시를 실행하려면 추가 도구와 OpenAI 설정이 필요해요.

uv pip install -U openai ddgs yfinance
export OPENAI_API_KEY="your-openai-api-key"
python callable_tools.py

콜러블 캐싱 설정

팩토리 결과는 기본적으로 캐시돼요. 캐시 키는 사용자 정의 키 함수 > user_id > session_id 순서로 정해지고, 셋 다 없으면 캐싱을 건너뛰고 매번 팩토리를 실행해요.

Setting	Default	Description
`cache_callables`	`True`	Enable or disable caching for all callable factories
`callable_tools_cache_key`	`None`	Custom cache key function for tools factory
`callable_knowledge_cache_key`	`None`	Custom cache key function for knowledge factory
`callable_members_cache_key`	`None`	Custom cache key function for members factory (Team only)

session_state가 실행마다 바뀌고 팩토리를 매번 다시 평가해야 한다면 cache_callables=False로 두면 돼요. 캐시를 지우려면 Agno 또는 Team 인스턴스를 clear_callable_cache()에 넘기면 돼요.

from agno.agent import Agent
from agno.team import Team
from agno.utils.callables import clear_callable_cache


def reset_tool_factory(entity: Agent | Team) -> None:
    clear_callable_cache(entity, kind="tools", close=True)

kind를 생략하면 해당 인스턴스의 모든 팩토리 캐시를 지워요. close=False(기본값)는 닫지 않고 결과만 제거하고, 비동기 코드에서는 aclear_callable_cache()를 써요.

다음 단계

기본에 익숙해지면 필요에 따라 기능을 추가해요. 세션 관리, 입출력, 도구, 컨텍스트, 지식, 멀티모달, 가드레일 등이 모두 개별 가이드로 나뉘어 있어요.

Agno 에이전트 만들기(Building Agents)