Agno Tools & Guardrails

상위: Agno

요약

Agno의 Tools는 에이전트가 외부 시스템과 상호작용하는 함수이며, Guardrails는 입력을 검증하여 안전하지 않은 요청을 차단하는 보호 장치이다. 120+ 내장 도구, MCP 지원, 커스텀 도구 정의, 그리고 PII 탐지/프롬프트 인젝션 방어 등의 가드레일을 제공한다.

Tools — 외부 시스템 연결

동작 원리

1. Agent → Model에 컨텍스트 + 도구 정의(JSON Schema) 전송
2. Model → 도구 호출 요청 반환 (또는 최종 응답)
3. 도구 실행 → 결과를 Model에 반환
4. 반복 (최종 응답이 나올 때까지)

Agno가 Python 함수의 타입 힌트와 docstring을 파싱하여 자동으로 JSON Schema 도구 정의를 생성한다. 별도 스키마를 수동 작성할 필요가 없다.

내장 도구 (120+)

커스텀 도구 생성

일반 Python 함수를 그대로 도구로 사용한다:

def get_weather(city: str) -> str:
    """Get current weather for a city.

    Args:
        city: The city name to look up weather for.
    """
    return f"The weather in {city} is sunny, 22°C."

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[get_weather],  # 일반 함수가 도구가 됨
)

docstring의 Args 섹션이 도구 파라미터 설명으로 자동 변환된다.

E2B Sandbox — 안전한 코드 실행

E2BTools로 클라우드 샌드박스에서 코드를 실행한다. 에이전트가 생성한 코드를 격리된 환경에서 안전하게 실행·검증할 수 있다.

from agno.tools.e2b import E2BTools

# 전체 기능
agent = Agent(tools=[E2BTools(timeout=600)])

# 기능 제한 (보안 강화)
safe_tools = E2BTools(
    timeout=600,
    include_tools=["run_python_code", "list_files", "read_file_content"],
)
agent = Agent(tools=[safe_tools])

주요 기능: run_python_code, upload_file, download_file_from_sandbox, list_files, read/write_file_content, run_server, get_public_url 등.

MCP (Model Context Protocol) 지원

MCP는 에이전트가 외부 시스템과 표준화된 인터페이스로 통신하는 프로토콜이다. Agno는 MCP Server와 Client 양쪽을 지원한다.

from agno.tools.mcp import MCPTools, MultiMCPTools

# 단일 MCP 서버 연결
agent = Agent(tools=[MCPTools(url="https://docs.agno.com/mcp")])

# 여러 MCP 서버 동시 연결
agent = Agent(tools=[MultiMCPTools(urls=[
    "https://server1.com/mcp",
    "https://server2.com/mcp",
])])

모든 모델 프로바이더에서 MCP를 사용할 수 있다 (유니버설 클라이언트).

A2A Protocol (Agent-to-Agent)

Google의 Agent2Agent 프로토콜로 에이전트 간 통신을 지원한다. MCP가 agent↔tool 통신이라면, A2A는 agent↔agent 통신이다. Agno 에이전트/팀을 A2A 호환 형식으로 노출할 수 있다.

@tool 데코레이터 전체 파라미터

from agno.tools import tool

@tool(
    name="fetch_stories",                  # 커스텀 이름 (기본: 함수명)
    description="Get top stories",         # 커스텀 설명 (기본: docstring)
    requires_confirmation=True,            # HITL: 실행 전 승인 필요
    stop_after_tool_call=True,             # 도구 실행 후 즉시 반환
    cache_results=True,                    # 결과 캐싱 활성화
    cache_dir="/tmp/agno_cache",           # 캐시 디렉토리
    cache_ttl=3600,                        # 캐시 TTL (초)
    pre_hook=my_pre_hook,                  # 실행 전 훅
    post_hook=my_post_hook,                # 실행 후 훅
    tool_hooks=[logger_hook],              # 래퍼 훅
)
def my_tool(num: int = 5) -> str:
    ...

도구 고급 기능

• 동시 실행: arun() 사용 시 도구가 병렬 실행. 시간이 오래 걸리는 도구에 유용
• 내장 파라미터: run_context, agent, images, videos 등을 도구 함수에 자동 주입
• Callable Factories: 역할/컨텍스트에 따라 도구를 동적으로 생성 (시그니처 기반 의존성 주입)
• ToolResult: 이미지 등 미디어를 반환할 때 사용하는 특수 반환 타입
• 도구 호출 제한: tool_call_limit으로 최대 호출 횟수 설정

Hooks 시스템

도구 실행·응답을 가로채는 pre/post hook, tool_hooks, RetryAgentRun, OutputCheckError는 Agno Hooks로 분리.

Guardrails — 입력 보호

에이전트와 팀에 대한 입력측 보호 장치이다. LLM에 요청이 전달되기 전에 검증한다.

내장 가드레일

동작 방식

from agno.agent import Agent
from agno.guardrails import PIIDetectionGuardrail

agent = Agent(
    name="Safe Agent",
    model=model,
    pre_hooks=[PIIDetectionGuardrail()],  # 입력 전처리 훅
)

가드레일이 위반을 감지하면 InputCheckError를 발생시키고, CheckTrigger로 위반 유형을 분류한다.

커스텀 가드레일

BaseGuardrail을 상속하여 커스텀 검증 로직을 작성한다:

from agno.guardrails import BaseGuardrail
from agno.exceptions import InputCheckError, CheckTrigger

class URLBlockGuardrail(BaseGuardrail):
    def check(self, run_input):
        if re.search(r'https?://', run_input.text):
            raise InputCheckError(
                "URLs are not allowed",
                check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
            )

Human-in-the-Loop (HITL)

→ Agno HITL 참조. Agent 수준(도구 단위)과 Workflow 수준(스텝 단위) HITL 패턴, Pause/Resume, 스트리밍+HITL, AgentOS API.

관련 개념

• Agno: Agno 프레임워크 MOC
• Agno Agent: 단일 에이전트 구성
• Agno HITL: Human-in-the-Loop 패턴
• Agno AgentOS: 프로덕션 배포 시 HITL 활용