도구(Tools) 설정하기

도구(Tools) 설정하기

에이전트가 단순히 말만 하는 수준을 넘어 실제로 무언가 작업하려면 **도구(tool)**가 필요해요. OpenAI Agents SDK에서 도구는 파이썬 함수(또는 비동기 함수)를 구조화된 도구로 바꿔서 모델이 호출할 수 있게 해주는 개념이에요. 도구 정의만 해 두면 SDK가 함수 시그니처와 docstring을 바탕으로 JSON 스키마를 만들어 모델에게 노출해요.

함수 도구 만들기

기본적으로 함수 정의 + docstring + 타입 힌트만 있으면 도구가 돼요. @function_tool 데코레이터를 쓰면 파이썬 함수를 도구로 등록할 수 있어요.

from agents import Agent, function_tool

@function_tool
def fetch_weather(city: str) -> str:
    """Return the current weather for a city.

    Args:
        city: The city name.
    """
    return f"It's sunny in {city}"

docstring의 Args: 부분이 모델에게 파라미터 설명으로 전달되니, 정확히 적어 두는 게 중요해요. 함수 docstring을 안 쓰거나 타입 힌트가 없으면 SDK가 스키마를 만들지 못할 수 있어요.

이 도구를 에이전트에 붙일 때는 Agent(..., tools=[fetch_weather])처럼 리스트로 넘기면 돼요.

agent = Agent(
    name="Weather agent",
    instructions="Answer weather questions.",
    tools=[fetch_weather],
)

도구를 직접 만들어 쓰기

@function_tool이 커버하지 못하는 커스텀 동작(인증 헤더, 진행 로그, 스트리밍 등)이 필요하다면 FunctionTool을 직접 구성할 수도 있어요. FunctionTool(name=..., description=..., params_json_schema=..., on_invoke_tool=...) 형태로 스키마와 실행 함수를 명시적으로 넘겨요. 실행 컨텍스트(RunContextWrapper)에 접근해야 할 때는 도구 함수가 RunContextWrapper를 첫 인자로 받도록 만들면 돼요.

에이전트를 도구로 사용하기

전문화된 에이전트를 다른 에이전트가 호출할 수 있는 도구로 만들 수도 있어요. Agent.as_tool()로 에이전트를 도구처럼 감싸면, 풀 핸드오프 없이 에이전트를 함수처럼 사용할 수 있어요. 중첩 입력 스키마를 원하면 include_input_schema=True를, 입력 구성을 완전히 바꾸려면 input_builder=...를 써요. 실행 컨텍스트의 RunContextWrapper.tool_input에 구조화된 페이로드가 담겨요.

도구 가드레일

도구 호출 전후로 검증을 넣고 싶다면 도구 가드레일을 써요. @tool_input_guardrail은 도구가 실행되기 전에, @tool_output_guardrail은 실행 후에 동작해서 호출을 거부하거나 출력을 교체할 수 있어요.

from agents import Agent, Runner
from agents.decorators import tool, tool_input_guardrail, tool_output_guardrail
import json

@tool_input_guardrail
def block_secrets(data):
    args = json.loads(data.context.tool_arguments or "{}")
    if "sk-" in json.dumps(args):
        return ToolGuardrailFunctionOutput.reject_content("Remove secrets before calling this tool.")
    return ToolGuardrailFunctionOutput.allow()

@tool(
    tool_input_guardrails=[block_secrets],
)
def classify_text(text: str) -> str:
    """Classify text for internal routing."""
    return f"length:{len(text)}"

agent = Agent(name="Classifier", tools=[classify_text])
result = Runner.run_sync(agent, "hello world")

도구 타입 비교

  • Function tools: 파이썬 함수 기반의 가장 흔한 도구예요.
  • Agents as tools: 에이전트를 도구로 감싸 중첩 실행을 하는 방식이에요.
  • Hosted tools: 플랫폼이 제공하는 도구(예: 프로그램형 도구 호출)로, @function_tool(defer_loading=True) 같은 설정으로 지연 로딩할 수 있어요.

도구 목록을 상황에 맞게 골랐다면, 어떤 런타임을 직접 제어하는지에 따라 해당 섹션을 참고하면 돼요.

더 알아보기