현장에서 에이전트 PoC가 흔들리는 지점은 의외로 모델 선택이 아니다. 같은 모델을 써도 어떤 팀은 업무를 끝까지 밀고 가고, 어떤 팀은 엉뚱한 툴을 부르거나 필드를 비워 둔다. 차이는 하네스에 있다. 더 정확히는 툴 스키마에 있다.
에이전트에게 툴 스키마는 API 문서가 아니다. 실행 시점에 매번 읽히는 작업 지시문이다. 사람이 함수명을 보고 대충 이해하듯, 모델도 name, description, input_schema, 에러 응답을 보고 다음 행동을 정한다.
툴 스키마는 백엔드 명세가 아니라 에이전트의 작업 언어다.
툴 이름은 라우팅 규칙이다
툴 이름은 짧아야 하지만 모호하면 안 된다. search, lookup, update 같은 이름은 사람에게도 불친절하고 모델에게도 불친절하다. 특히 여러 업무 도메인의 툴을 한 에이전트에 붙이면 이름 충돌이 곧 오작동으로 이어진다.
좋은 이름은 세 가지를 드러낸다. 도메인, 행위, 대상이다.
| 나쁜 이름 | 좋은 이름 | 이유 |
|---|---|---|
search |
kb_search_policy_documents |
검색 대상이 명확하다 |
update_user |
crm_update_customer_contact |
시스템과 객체가 드러난다 |
send |
slack_send_channel_message |
부작용이 있는 툴임을 알린다 |
OpenAI Agents SDK 문서는 함수 툴을 만들 때 함수 이름, docstring, 입력 인자를 기반으로 툴 이름·설명·스키마를 구성한다고 설명한다. Anthropic Claude API 문서도 툴 정의의 name, description, input_schema를 별도 구성 요소로 다룬다. 이 말은 간단하다. 코드 내부에서만 통하던 함수명이 이제 모델의 의사결정 재료가 됐다.
Description은 사용 조건까지 써야 한다
많은 팀이 description을 한 줄 기능 설명으로 끝낸다. 그것은 부족하다. description에는 무엇을 하는지뿐 아니라 언제 쓰고, 언제 쓰지 않으며, 무엇을 반환하고, 어떤 제약이 있는지가 들어가야 한다.
나쁜 description은 이렇다.
고객 정보를 조회한다.
운영 가능한 description은 다르다.
CRM에서 customer_id로 단일 고객 프로필을 조회한다. 고객 식별자가 확인된 뒤에만 사용한다. 이름이나 이메일만 있는 경우 먼저 고객 검색 툴을 사용한다. 반환값은 고객 기본 정보, 등급, 최근 접촉 이력이다. 결제 정보는 반환하지 않는다.
이 정도로 써야 모델이 툴 선택, 선행 질문, 후속 툴 호출을 구분한다. Anthropic 문서는 clear description이 툴의 동작, 사용 시점, 반환 데이터, 파라미터 의미를 설명해야 한다고 명시한다. MCP 스펙도 툴을 name, title, description, inputSchema, outputSchema, annotations의 조합으로 정의한다. description은 장식 문구가 아니다. 런타임 정책이다.
에러 메시지는 재시도 지시문이다
에러 메시지를 사람용 로그처럼 던지면 에이전트는 복구하지 못한다. 500 Internal Server Error, invalid request, not found는 운영자에게도 부족하고 모델에게도 부족하다.
에러 응답은 세 가지를 가져야 한다.
- 무엇이 실패했는가
- 재시도 가능한가
- 다음 행동은 무엇인가
예시는 이렇다.
CUSTOMER_NOT_FOUND: customer_id와 일치하는 고객이 없다. retryable=false. 사용자가 제공한 이름 또는 이메일로 crm_search_customer를 먼저 호출하라.
RATE_LIMITED: CRM API 호출 한도를 초과했다. retryable=true. 30초 후 같은 인자로 1회만 재시도하라.
OpenAI Agents SDK는 툴 실행 실패 시 모델에게 전달할 오류 메시지를 커스터마이즈하는 failure_error_function과 tool_error_formatter를 제공한다. 이것은 단순 예외 처리가 아니다. 모델이 다음 스텝을 고르는 데 쓰는 제어면이다.
반대로 스택트레이스, 내부 테이블명, 권한 토큰, 원본 쿼리를 그대로 노출하면 보안과 품질이 동시에 무너진다. 에러는 감추는 것이 아니라 정제해서 돌려줘야 한다.
참고와 다음 행동은 스키마 리뷰에서 시작한다
최근 에이전트 하네스 논의는 모델 프롬프트에서 툴 인터페이스로 이동했다. Claude Code의 hooks, subagents, MCP 연동도 결국 툴을 언제 부르고 어떤 결과를 믿을지의 문제로 수렴한다. OpenAI의 Agents SDK도 툴, 에러 처리, 샌드박스 실행을 하네스의 핵심 요소로 다룬다.
참고한 1차 출처는 다음과 같다.
- Anthropic Claude API, Define tools, 2026년 7월 확인: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
- Anthropic Claude API, Tool use overview, 2026년 7월 확인: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
- OpenAI Agents SDK, Function tools and error handling, 2026년 7월 확인: https://openai.github.io/openai-agents-python/tools/
- OpenAI Agents SDK, Running agents and tool error formatter, 2026년 7월 확인: https://openai.github.io/openai-agents-python/running_agents/
- Model Context Protocol Schema Reference, 2025-11-25: https://modelcontextprotocol.io/specification/2025-11-25/schema
- OpenAI, The next evolution of the Agents SDK, 2026: https://openai.com/index/the-next-evolution-of-the-agents-sdk/
- Anthropic, Claude Code Advanced Patterns, 2026: https://www.anthropic.com/webinars/claude-code-advanced-patterns
AX LABS가 보는 첫 점검 대상은 모델이 아니라 툴 카탈로그다. 이름을 정리하고, description을 정책 문장으로 바꾸고, 에러 메시지를 복구 지시문으로 바꾸면 에이전트의 실행 안정성이 바로 달라진다. 운영으로 가는 에이전트 설계는 하네스에서 시작한다. 더 구체적인 설계 원칙은 AX Ops 방법론 →에서 다룬다.
