3 - Agents SDK의 핵심 개념

 

– Agent, Tool, Function Calling, Guardrail 한 번에 이해하기

안녕하세요. 지난 글에서는 Python에서 OpenAI Agents SDK를 설치하고, 간단한 에이전트를 실행해보는 실습을 진행했습니다.
이제 본격적으로 이 SDK의 핵심 개념들을 알아볼 차례입니다.

Agents SDK는 구조가 단순하지만 강력합니다.
이번 글에서는 다음 네 가지 개념을 집중적으로 다룹니다:

• Agent (에이전트)
• Tool (도구)
• Function Calling (함수 호출)
• Guardrail (가드레일)

각 개념은 하나씩 알아두면 별것 아니지만, 제대로 활용하면 GPT를 진짜 “작업을 수행하는 AI”로 만드는 핵심 구성요소가 됩니다.

---

🤖 1. Agent – 우리의 AI 비서 본체

Agent는 하나의 GPT 모델 인스턴스이며, 우리가 정의한 지시어(instructions)와 이름(name)을 기준으로 역할을 부여받습니다.

from agents import Agent

agent = Agent(
    name="ScheduleBot",
    instructions="너는 사용자에게 친절하게 일정을 도와주는 비서야."
)

• name: 로그 추적이나 식별용
• instructions: Agent의 성격, 역할, 말투, 행동 범위를 정의하는 핵심

이 지시어는 ChatGPT에서 사용하는 “System Prompt”와 같은 역할을 합니다.
예를 들어, 지금부터 너는 일정 도우미 역할을 맡아. 날짜와 시간을 인식해서 일정 조회를 도와줘.라고 지시하면, Agent는 그에 따라 행동합니다.

Agent는 단일 메시지를 처리하거나, 이전 대화 히스토리를 포함한 멀티턴 대화도 처리할 수 있습니다. (이 부분은 4편 이후에서 다룹니다.)

---

🛠 2. Tool – 에이전트가 사용할 수 있는 실제 기능

에이전트는 자체적으로 API를 호출하거나 데이터를 불러올 수는 없습니다.
하지만 우리가 만든 Python 함수를 Tool로 등록하면, 에이전트가 그것을 호출할 수 있습니다.

✅ 도구 등록 예시

from agents import function_tool

@function_tool
def get_weather(city: str) -> str:
    """도시 이름을 받아 날씨를 알려줍니다."""
    return f"{city}의 날씨는 맑음입니다."

• @function_tool 데코레이터를 붙이면 해당 함수는 자동으로 Tool로 등록됩니다.
• 함수의 시그니처와 docstring이 모델에게 설명으로 전달됩니다.

GPT는 Tool을 사용할 수 있는 상황에서, “아 이건 get_weather를 쓰면 되겠네”라고 스스로 판단해 해당 함수를 호출하려고 시도합니다.

에이전트 생성 시 Tool을 추가해줍니다:

agent = Agent(
    name="날씨비서",
    instructions="너는 날씨 정보를 제공하는 도우미야.",
    tools=[get_weather]
)

이제 "서울 날씨 알려줘" 같은 질문을 받으면 Agent는 get_weather("서울")을 호출하려고 하게 됩니다.

---

🔁 3. Function Calling – GPT가 함수를 호출하는 방식

GPT는 원래 텍스트 생성에 특화되어 있지만, OpenAI는 여기에 함수 호출(function calling)이라는 능력을 추가했습니다.

Agents SDK는 이 기능을 자동으로 활용합니다.
즉, GPT가 “이 질문은 도구가 필요해”라고 판단하면, 도구 이름과 인자를 JSON 형식으로 반환하고, SDK가 그걸 실제로 실행합니다.

내부적으로 일어나는 흐름은 다음과 같습니다:

[사용자 질문] → [GPT가 도구 필요 판단] → [도구 이름과 인자 생성]  
→ [SDK가 해당 함수 호출] → [결과 GPT에게 전달] → [최종 응답 생성]

개발자는 단순히 Tool로 사용할 함수만 정의하면 됩니다.
GPT가 알아서:

• 어떤 도구를 쓸지 판단하고,
• 필요한 인자를 구성해서,
• 호출하고,
• 결과를 사용해 답을 만듭니다.

이 모든 과정을 “에이전트 루프(agent loop)”라고 부릅니다.

---

🧱 4. Guardrail – 입력과 출력의 안전망

Guardrail은 에이전트의 입력이나 출력에 대한 검증 도구입니다.
예를 들어, 사용자 입력에 욕설이 있으면 차단하거나, 에이전트 응답이 너무 길면 오류를 내는 식입니다.

✅ 입력 Guardrail 예시

from agents import input_guardrail

@input_guardrail
def check_for_profanity(text: str):
    if "욕설" in text:
        raise ValueError("금지된 단어가 포함되어 있습니다.")

✅ 출력 Guardrail 예시

from agents import output_guardrail

@output_guardrail
def limit_response_length(response: str):
    if len(response) > 500:
        raise ValueError("응답이 너무 깁니다.")

이러한 Guardrail은 Agent에 추가해서 사용할 수 있습니다:

agent = Agent(
    name="안전한비서",
    instructions="너는 정중하고 신뢰할 수 있는 AI야.",
    input_guardrails=[check_for_profanity],
    output_guardrails=[limit_response_length]
)

실무에서는 보안, 검열, 포맷 검증 등에 Guardrail이 매우 유용합니다.

---

🔄 5. 멀티턴 대화와 Handoff (간단 소개)

앞으로 다룰 내용 중에는 Agent 간 위임(Handoff) 기능도 있습니다.
즉, 어떤 Agent가 “이건 내가 아닌 다른 전문가 Agent가 처리해야겠다”고 판단하면, 그 Agent에게 질문을 넘기고 결과를 받아 최종 답을 만드는 구조입니다.

예:

• Manager Agent → 일정 질문이면 Schedule Agent에게 넘김
• Schedule Agent → 일정 도구 호출 후 요약하여 반환

이 기능은 5편 이후에서 다룰 예정입니다.

---

🧠 요약

개념	역할
Agent	GPT 모델 + 역할 지시어. 우리의 AI 비서 본체
Tool	에이전트가 호출할 수 있는 Python 함수
Function Calling	GPT가 도구가 필요할 때 직접 호출하도록 유도하는 메커니즘
Guardrail	입력과 출력에 대한 필터/검증. 실무에선 필수

---

✅ 마무리하며

이제 Agents SDK의 가장 핵심이 되는 개념들을 이해하셨습니다.
이제 다음 글에서는 이러한 개념을 코드로 직접 구현하면서 실습해볼 차례입니다.

다음 글: 4 - 간단한 에이전트부터 FastAPI 연동까지 실습하기