Clip 3 발표 스크립트: AI Agent가 사용할 툴은 AI로 만들어야 하는 이유
🎯 발표 개요
- 예상 시간: 15-20분
- 핵심 메시지: AI 에이전트를 위한 툴은 단순히 API를 래핑하는 것이 아니라, 워크플로우 중심으로 설계해야 성능이 극대화된다
- 실습 포함: Claude Code를 활용한 툴 프로토타이핑 시연
📖 발표 스크립트
[인트로] (2분)
안녕하세요. 이번 시간에는 AI 에이전트가 사용할 툴을 AI로 만들어야 하는 이유에 대해 알아보겠습니다.
[화면: Anthropic 엔지니어링 블로그 링크 표시]
이 내용은 Anthropic의 공식 엔지니어링 블로그에서 발표한 내용을 기반으로 합니다. 실제로 Claude를 만든 팀이 직접 검증한 best practice라는 점에서 매우 신뢰할 수 있는 가이드라인입니다.
오늘의 핵심 질문은 이겁니다:
"왜 우리가 이미 가지고 있는 API를 그냥 툴로 래핑하면 안 될까요?"
이 질문에 대한 답을 함께 찾아가보겠습니다.
[섹션 1] 전통적 접근의 한계 (3분)
[화면: 코드 예시 - 여러 개의 툴 나열]
여러분이 AI 에이전트를 만든다고 상상해보세요. 가장 먼저 떠오르는 생각은 뭘까요?
아마 이렇게 생각하실 겁니다: "우리 회사 API가 30개니까, 30개 툴을 만들어서 에이전트에 연결하면 되겠네!"
tools = [
list_users_tool,
list_events_tool,
create_event_tool,
update_event_tool,
delete_event_tool,
send_notification_tool,
# ... 수십 개
]하지만 이 접근법에는 3가지 치명적인 문제가 있습니다:
- 선택의 혼란: 에이전트가 30개 툴 중 어떤 걸 써야 할지 헷갈립니다
- 복잡성 증가: 간단한 작업도 5-6개 툴을 순차 호출해야 합니다
- 컨텍스트 낭비: 툴 설명만으로 컨텍스트 윈도우가 가득 차버립니다
[잠시 멈춤, 청중 반응 확인]
그렇다면 왜 이런 문제가 생길까요?
[섹션 2] 핵심 통찰: 에이전트 ≠ 결정론적 시스템 (4분)
[화면: 비교 표 표시]
핵심은 바로 이겁니다:
"AI 에이전트는 결정론적 시스템이 아닙니다"
전통적인 프로그래밍에서는 개발자가 정확히 어떤 함수를 언제 호출할지 코드로 명시합니다. 하지만 AI 에이전트는 LLM이 스스로 판단해서 툴을 선택합니다.
| 구분 | 전통적인 API | AI 에이전트 |
|---|---|---|
| 동작 방식 | 결정론적, 예측 가능 | 비결정론적, 추론 기반 |
| 에러 처리 | 명확한 에러 코드 | 자연어로 이해하고 대응 |
| 컨텍스트 | 무제한 메모리 | 제한된 컨텍스트 윈도우 |
| 툴 선택 | 프로그래머가 명시 | LLM이 자율적으로 선택 |
[화면: Mermaid 다이어그램 - 전통적 API vs AI 에이전트 비교]
예를 들어볼게요. 사용자가 이렇게 요청했다고 해봅시다: "다음 주 Jane과 회의 잡아줘"
전통적 API 방식이라면:
list_users()- 사용자 목록 조회find_jane()- Jane 찾기list_events()- 이벤트 목록check_availability()- 가용 시간 확인create_event()- 이벤트 생성send_notification()- 알림 전송
6단계나 거쳐야 합니다!
워크플로우 중심 설계라면:
schedule_meeting(participant="Jane", next_week=True)- 끝!
한 번에 처리됩니다.
[섹션 3] 워크플로우 중심 설계란? (4분)
자, 그럼 어떻게 해야 할까요?
핵심 원칙은 이겁니다:
"더 많은 툴"이 아니라 "더 똑똑한 툴"
[화면: Before/After 코드 비교]
전통적 설계 (API 래핑):
@tool
def list_customers(): pass
@tool
def get_customer_transactions(customer_id): pass
@tool
def get_customer_notes(customer_id): pass워크플로우 중심 설계:
@tool
def get_customer_context(
customer_id: str,
include_transactions: bool = True,
include_notes: bool = True,
response_format: ResponseFormat = ResponseFormat.CONCISE
):
"""
고객 지원 담당자가 필요한 모든 정보를 한 번에 제공
"""실제 성능 차이를 보여드릴게요.
Anthropic 팀이 Slack 메시지 조회 기능을 개선한 사례입니다:
- Before: 3개 툴 순차 호출 → 206 토큰 사용
- After: 1개 통합 툴 → 72 토큰 사용
65% 토큰 절감! 비용도 줄고, 속도도 빨라지고, 에러도 줄어듭니다.
[섹션 4] 3가지 핵심 패턴 (3분)
제가 강의 자료에 3가지 패턴을 정리했는데, 핵심만 짚어드리겠습니다.
Pattern 1: Response Format 제어
class ResponseFormat(Enum):
DETAILED = "detailed" # 후속 작업용, 모든 필드 포함
CONCISE = "concise" # 사용자 보고용, 핵심만왜 이게 중요할까요?
에이전트가 정보를 단순히 보여줄 때와 다른 툴에 전달할 때 필요한 데이터가 다르기 때문입니다.
- 사용자에게 보고: "John Doe, 최근 구매 $299" (CONCISE)
- 다른 툴로 전달: trace_id, span_id 등 모든 메타데이터 (DETAILED)
Pattern 2: 네임스페이스 일관성
asana_search_tasks()
asana_create_task()
github_search_issues()
github_create_issue()search_tasks와 search_issues를 구분하기 어렵습니다. 하지만 asana_, github_ 접두사를 붙이면 에이전트가 혼동하지 않습니다.
Pattern 3: 스마트 기본값
def schedule_event(
title: str,
participants: list[str],
duration_minutes: int = 30, # 일반적인 회의 시간
auto_find_room: bool = True, # 자동 회의실 찾기
auto_send_invite: bool = True # 자동 초대장 발송
):대부분의 회의가 30분이고, 회의실이 필요하고, 초대장을 보내야 하죠. 이런 일반적인 케이스를 기본값으로 설정하면 에이전트가 훨씬 효율적으로 작동합니다.
[섹션 5] 실습: Claude Code로 프로토타이핑 (3분)
[화면: 터미널 준비]
자, 이제 가장 흥미로운 부분입니다.
**"AI 툴을 AI로 만든다"**는 게 무슨 의미일까요?
바로 Claude Code를 사용해서 에이전트 툴을 설계하고 테스트하는 겁니다!
[시연 시작]
claude code[Claude Code에 프롬프트 입력]
나는 고객 지원 AI 에이전트를 만들고 있어.
현재 문제:
- get_customer(), get_transactions(), get_support_tickets()
3개 툴을 매번 순차적으로 호출해야 함
- 토큰 소비가 많고, 에러 가능성 높음
요청:
다음 기능을 제공하는 통합 툴 `get_customer_context`를 설계해줘:
1. 고객 기본 정보, 거래 내역, 지원 티켓을 한 번에 조회
2. response_format 파라미터로 CONCISE/DETAILED 모드 지원
3. 선택적으로 특정 정보만 가져올 수 있는 옵션 제공
4. LLM이 이해하기 쉬운 docstring 작성
참고: Anthropic의 best practice를 따라줘
https://www.anthropic.com/engineering/writing-tools-for-agents[Claude Code가 코드 생성하는 것을 지켜봄]
보시다시피, Claude Code가:
- 워크플로우를 이해하고
- 적절한 파라미터를 설계하고
- LLM 친화적인 docstring을 작성했습니다
그리고 이걸 바로 MCP 서버로 만들어서 테스트할 수 있습니다!
[섹션 6] 평가 자동화 (2분)
마지막으로 중요한 점 하나.
"만들고 끝"이 아니라 "평가"를 자동화해야 합니다.
[화면: 평가 코드 예시]
def evaluate_agent_tools(test_cases):
metrics = {
'accuracy': [], # 정확도
'tool_calls': [], # 툴 호출 횟수
'tokens_used': [], # 토큰 소비량
'errors': [] # 에러율
}
# ...측정 가능한 지표:
- 📊 정확도: 예상 결과와 일치하는가?
- 📊 효율성: 툴 호출 횟수, 토큰 사용량
- 📊 안정성: 에러율은 얼마나 되는가?
Anthropic은 이렇게 프로그래밍 방식으로 평가를 자동화하라고 권장합니다.
[마무리] (2분)
자, 오늘 배운 내용을 정리해볼게요.
핵심 5가지:
- 패러다임 전환: AI 에이전트 툴은 API 래핑이 아니라 워크플로우 설계
- 더 적은 툴, 더 높은 품질: 3개 툴 → 1개 통합 툴로 성능 65% 향상
- Response Format 제어: CONCISE/DETAILED로 토큰 효율성 극대화
- Claude Code로 프로토타이핑: AI를 사용해 AI 툴 설계
- 평가 자동화: 프로그래밍 방식으로 정확도, 효율성 측정
[화면: 체크리스트 표시]
실무에 적용하실 때 이 체크리스트를 확인해보세요:
✅ 워크플로우 중심인가? ✅ CONCISE/DETAILED 옵션 제공하는가? ✅ 명확한 네임스페이스가 있는가? ✅ 스마트 기본값을 설정했는가? ✅ LLM 친화적인 docstring인가? ✅ 평가 가능한가?
마지막으로 한 가지 더.
Anthropic이 강조한 말이 있습니다:
"Agents are only as effective as the tools we give them."
"에이전트는 우리가 제공하는 툴만큼만 효과적입니다."
아무리 강력한 LLM이라도, 잘못 설계된 툴을 주면 성능이 나쁩니다. 반대로 잘 설계된 툴을 주면, 더 작은 모델로도 훌륭한 결과를 낼 수 있습니다.
여러분의 다음 프로젝트에서는 API를 그냥 래핑하지 마시고, 실제 업무 워크플로우를 고민해서 툴을 설계해보세요.
그리고 그 툴을 설계할 때, Claude Code를 활용해보시기 바랍니다.
[화면: 참고 자료 링크 표시]
더 자세한 내용은 강의 자료에 있는 Anthropic 공식 블로그 링크를 참고하시고, 질문 있으시면 편하게 해주세요!
감사합니다.
🎤 발표 팁
시간 배분
- 인트로: 2분
- 섹션 1-2: 7분 (문제 정의 + 핵심 통찰)
- 섹션 3-4: 7분 (해결 방법 + 패턴)
- 섹션 5-6: 5분 (실습 + 평가)
- 마무리: 2분
청중 참여 포인트
- "여러분이라면 어떻게 하시겠어요?" (섹션 1에서 질문)
- 실시간 시연 (섹션 5에서 Claude Code 사용)
- 성능 수치 강조 (65% 토큰 절감 - 구체적 수치는 기억에 남음)
주의사항
- 코드는 너무 오래 보여주지 말고, 핵심만 강조
- Mermaid 다이어그램을 활용해 시각적으로 설명
- 실습 시연은 미리 리허설 필수 (라이브 코딩은 위험)
- 복잡한 기술 용어보다 워크플로우, 업무 흐름 같은 친숙한 단어 사용
백업 플랜
- Claude Code 시연이 안 되면: 미리 녹화한 영상 준비
- 시간이 부족하면: 섹션 6(평가) 축약 가능
- 질문이 많으면: 실습 부분 줄이고 Q&A 시간 확보
📊 예상 질문 & 답변
Q1: 기존 API가 100개인데, 어떻게 통합 툴로 만들죠?
A: 좋은 질문입니다. 한 번에 다 할 필요는 없습니다. 먼저 가장 자주 쓰이는 워크플로우 3-5개를 찾아서 통합 툴로 만들어보세요. 예를 들어 "고객 정보 조회", "주문 처리", "환불 처리" 같은 핵심 업무 흐름부터 시작하시면 됩니다.
Q2: Response Format은 꼭 CONCISE/DETAILED 두 가지만 써야 하나요?
A: 아닙니다. 여러분의 도메인에 맞게 커스터마이즈하세요. 예를 들어 SUMMARY, FULL, DEBUG 같은 옵션을 추가할 수도 있습니다. 핵심은 "언제 어떤 정보가 필요한지" 고민하는 겁니다.
Q3: Claude Code 없이도 이런 툴을 설계할 수 있나요?
A: 물론입니다! Claude Code는 프로토타이핑을 빠르게 하기 위한 도구일 뿐입니다. 수작업으로도 충분히 좋은 툴을 설계할 수 있습니다. 다만 Claude Code를 쓰면 Anthropic의 best practice를 자동으로 적용해주고, LLM 친화적인 docstring을 작성해주니까 시간을 많이 절약할 수 있습니다.
Q4: 평가 자동화는 어떻게 시작하면 좋을까요?
A: 간단하게 시작하세요.
- 가장 중요한 워크플로우 3개 선정
- 각 워크플로우마다 "성공" 조건 정의 (예: "Jane의 캘린더에 이벤트 있음")
- 간단한 assert 문으로 검증
처음부터 완벽한 평가 시스템을 만들려고 하지 마세요. 점진적으로 개선하는 게 좋습니다.
Q5: 이 방법이 모든 AI 에이전트에 적용되나요?
A: 네, LLM 기반 에이전트라면 모두 해당됩니다. OpenAI Function Calling, Anthropic Tool Use, LangChain Agents 등 툴을 사용하는 모든 프레임워크에서 이 원칙이 적용됩니다. "워크플로우 중심 설계"는 프레임워크와 무관한 보편적 원칙입니다.
강사 정보
- 작성자: 정구봉
- LinkedIn: https://www.linkedin.com/in/gb-jeong/
- 이메일: bong@dio.so