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

 

– 첫 에이전트를 만들고, API 서버로 배포해보기

안녕하세요. 지난 글에서는 Agents SDK의 핵심 개념인 Agent, Tool, Function Calling, Guardrail에 대해 설명드렸습니다.
이제 본격적으로 코드를 작성해서 실제 작동하는 AI 에이전트를 만들어볼 차례입니다.

이번 글에서는 다음을 실습합니다:

1. 가장 단순한 “Hello Agent” 만들기
2. 사용자 정의 도구(tool)를 추가하기
3. FastAPI로 에이전트를 API 서버로 만들기

---

🧪 1. Hello Agent – 가장 단순한 실행 예제

에이전트는 Agent 클래스로 만들고, Runner.run_sync로 실행합니다.

# hello_agent.py
from agents import Agent, Runner

agent = Agent(
    name="hello-agent",
    instructions="당신은 사용자의 질문에 친절하게 답변하는 도우미입니다."
)

result = Runner.run_sync(agent, "안녕하세요! 오늘 날씨가 어떤가요?")
print(result.final_output)

실행:

python hello_agent.py

예상 출력 (모델에 따라 다를 수 있음):

안녕하세요! 오늘은 맑고 따뜻한 하루가 될 것 같아요. 산책이나 나들이 계획은 어떠세요?

✅ 설명

• Agent는 지시어(instructions)를 바탕으로 GPT의 응답 방식을 설정합니다.
• Runner는 에이전트를 실행해주는 헬퍼로, run_sync()는 동기 방식입니다.

---

🛠 2. 도구 추가하기 – 날씨 함수 사용

이제 에이전트에게 실제 기능(도구)을 하나 붙여봅시다.
예를 들어 “서울 날씨 알려줘”라는 요청에 대해 직접 구현한 함수로 응답하게 해보겠습니다.

# agent_with_tool.py
from agents import Agent, Runner, function_tool

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

agent = Agent(
    name="weather-agent",
    instructions="너는 날씨 정보를 알려주는 도우미야. 필요한 경우 get_weather 도구를 사용해.",
    tools=[get_weather]
)

result = Runner.run_sync(agent, "서울 날씨 어때?")
print(result.final_output)

실행 결과 (예상):

서울의 현재 날씨는 맑고 기온은 22도입니다.

✅ 포인트 요약

• @function_tool을 붙이면 해당 함수가 자동으로 Tool로 등록됩니다.
• GPT는 지시어와 질문을 보고, 도구가 필요하다고 판단되면 함수를 호출하려고 시도합니다.
• 실제 함수 호출과 결과 전달은 SDK가 자동 처리합니다.

---

🌐 3. FastAPI로 API 서버 만들기

에이전트를 실제 서비스에 활용하려면 웹 API 형태로 만들 필요가 있습니다.
FastAPI를 이용해 간단한 API 서버를 만들어봅니다.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel
from agents import Agent, Runner, function_tool

app = FastAPI()

@function_tool
def get_weather(city: str) -> str:
    return f"{city}의 현재 날씨는 맑고 기온은 22도입니다."

agent = Agent(
    name="api-agent",
    instructions="너는 사용자의 질문에 성실히 응답하고, 날씨 질문이 있다면 get_weather 도구를 사용해.",
    tools=[get_weather]
)

class Query(BaseModel):
    question: str

@app.post("/ask")
async def ask_agent(query: Query):
    result = await Runner.run(agent, input=query.question)
    return {"answer": result.final_output}

실행 방법

uvicorn main:app --reload

접속: http://localhost:8000/docs
Swagger UI에서 POST /ask 요청을 테스트할 수 있습니다.

요청 예:

{
  "question": "서울 날씨 알려줘"
}

응답 예:

{
  "answer": "서울의 현재 날씨는 맑고 기온은 22도입니다."
}

✅ 구성 설명

• Agent는 앱 실행 시 한 번만 생성해 공유합니다.
• API 요청이 들어오면 Runner.run()을 통해 비동기 실행합니다.
• 에이전트는 필요 시 등록된 도구를 자동으로 호출합니다.

---

🧭 4. 프로젝트 구조 추천

실무에서 유지보수를 고려하면, 다음과 같은 구조를 추천드립니다:

agents-practice/
├── agents/
│   ├── tools.py         # 도구 정의
│   └── agent.py         # 에이전트 설정
├── api/
│   └── main.py          # FastAPI 엔드포인트
├── .env
├── requirements.txt
└── README.md

각 도구와 에이전트 정의를 분리하면:

• 도구 테스트 및 변경이 쉬움
• 여러 에이전트 재사용 가능
• API 서버 코드가 깔끔해짐

---

🧠 정리

항목	내용
Agent	GPT 모델에 역할을 부여하고 실행 흐름 정의
Tool	Python 함수 하나로 기능 확장
Runner	실행을 담당하는 도우미. run_sync 또는 run 사용
FastAPI 연동	API 형태로 에이전트 노출. 실제 서비스에 연결 가능

---

✅ 마무리하며

이제 여러분은 단순한 질문에 답하는 에이전트를 넘어서, 도구를 사용하는 AI를 만들 수 있게 되었습니다.
또한 FastAPI를 활용해 실제 사용자와 상호작용 가능한 API 서버까지 구성했습니다.

다음 글: 5 - Agents SDK로 업무 자동화하기 – 이메일 요약부터 회신까지

다음 글에서는 Agents SDK를 이용해 이메일 업무를 자동화하는 멀티에이전트 워크플로우를 구현해보겠습니다.