용어집
《에이전트 도구 호출: 에이전트가 실제로 일하게 만들기》의 용어 76개. 레슨 본문에서 처음 등장하는 용어에 마우스를 올리면 정의를 볼 수 있습니다.
| 용어 | 정의 | 출처 |
|---|---|---|
| 도구 (tool) | 에이전트 맥락에서 도구란 모델이 대화 도중에 호출을 요청할 수 있는 구체적인 기능이다. 호스트 프로그램이 그것을 등록하고 실행하며, 그럼으로써 말만 하던 모델을 실제로 행동할 수 있는 존재로 바꾼다. | Define tools — Claude API |
| 호스트 프로그램 (host program) | 호스트 프로그램은 모델의 도구 호출 요청을 실제로 받아 작업을 실행하고 그 결과를 모델에게 되돌려주는 코드다. 예를 들어 Claude Code나 여러분이 직접 작성한 에이전트 스크립트가 여기에 해당한다. | How tool use works — Claude API |
| search_files | 코스 전반에서 쓰이는 예시 도구 이름으로, '어떤 조건으로 프로젝트 파일을 검색한다'는 부류의 구체적 도구 정의를 대표한다. | Define tools — Claude API |
| name | 도구 정의의 필수 필드로, 모델이 도구를 고를 때 적어 넣는 식별자이며 호출 시점에 주어진 이름과 정확히 일치해야 한다. | Define tools — Claude API |
| description | 도구 정의의 필수 필드로, 도구가 무엇을 하고 언제 써야 하며 어떻게 동작하는지를 평문으로 진술하며, 모델이 도구를 고를 때 근거로 삼을 수 있는 유일하게 읽을 수 있는 텍스트다. | Define tools — Claude API |
| input_schema | 도구 정의의 필수 필드로, 도구를 호출할 때 파라미터가 어떤 형태를 취해야 하는지를 지정하는 JSON Schema다. | Define tools — Claude API |
| client tools | 호스트 애플리케이션이 스스로 실행할 책임을 지는 도구다. 모델은 호출 요청만 생성하고, 실제 실행 코드는 호스트 쪽에서 돌아간다. | Tool use with Claude — Overview |
| server tools | Anthropic 서버가 여러분을 대신해 실행해 주는 도구로, 호스트 애플리케이션이 실행 로직을 직접 구현해야 하는 client tools와 대비된다. | Tool use with Claude — Overview |
| 구조화된 데이터 (structured data) | 모델의 도구 호출 요청은 자연어 지시가 아니라 한 덩어리의 구조화된 데이터로 돌아오며, 호스트 프로그램이 파싱해 실행할 수 있도록 도구 이름과 파라미터를 담고 있다. | How tool use works — Claude API |
| required | JSON Schema의 필드로, 도구 호출이 반드시 제공해야 하는 파라미터 이름을 나열한다. 그 파라미터가 빠진 호출은 유효하지 않은 입력으로 취급된다. | Define tools — Claude API |
| Claude Code | 코스에서 드는 '호스트 프로그램' 개념의 구체적 예시로, 그 자체가 여러 도구(파일 읽기, 코드 검색, 명령 실행 등)의 호출을 요청하는 에이전트 제품이다. | Tools reference — Claude Code Docs |
| tools | 모델에게 보내는 요청에 실리는 필드로, 이번 대화에서 모델이 호출을 요청할 수 있는 도구가 무엇이고 각각 어떤 파라미터가 필요한지 나열한 도구 명세서다. | Define tools — Claude API |
| stop_reason | 모델 응답의 필드로, 이번에 모델이 왜 말을 멈췄는지를 밝힌다. 값으로는 tool_use, end_turn 등이 있으며, 실행 기록이 아니라 신호일 뿐이다. | Tool use with Claude — Overview |
| tool_result | 모델에게 되돌려 보내는 메시지 안의 콘텐츠 블록 종류로, 도구 실행이 끝난 결과를 담으며 tool_use_id로 대응하는 tool_use 블록과 짝을 맞춘다. | Handle tool calls — Claude API |
| tool_use_id | tool_result 블록의 필드로, 대응하는 tool_use 블록의 id와 정확히 일치해야 한다. 모델은 이것으로 각 결과를 그 요청과 짝지운다. | Handle tool calls — Claude API |
| is_error | tool_result 블록의 선택 필드로, 이번 도구 실행 자체가 실패했는지 표시한다. true로 설정하면 이 호출이 문제를 만났다는 것을 모델에게 알린다. | Handle tool calls — Claude API |
| finish_reason | OpenAI 호환 API에서 stop_reason에 대응하는 필드 이름으로, 값이 tool_calls이면 모델이 도구 호출을 요청하는 중이라는 뜻이다. | Tool Use — LM Studio Docs (OpenAI-compatible API) |
| messages | 요청 안에서 대화 이력을 담는 배열 필드로, 매 턴의 응답을 글자 그대로 여기에 추가해야 하며, 여기에는 모델의 tool_use 응답과 그 뒤의 tool_result가 모두 포함된다. | How tool use works — Claude API |
| end_turn | stop_reason의 한 값으로, 모델이 이번 턴에 할 말을 다 했고 더 이상 도구 호출이 필요 없으며 그 content를 사용자에게 건네도 된다는 뜻이다. | Tool use with Claude — Overview |
| tool_use 블록 (tool_use block) | 모델 응답의 content 배열에 담기는 콘텐츠 블록 종류로, 하나의 도구 호출 요청을 나타낸다. id, name, input 세 필드를 모두 지녀야 비로소 완전하다. | Handle tool calls — Claude API |
| 왕복 (round-trip) | 도구 호출 한 번의 전체 주기다. 모델이 요청을 내보내고, 호스트가 그것을 실행하고, 결과가 되돌려 보내지고, 모델이 다음 응답을 내놓는 것까지를 이른다. | How tool use works — Claude API |
| 루프 (loop) | 멀티턴 도구 호출을 처리하는 호스트 쪽 방식이다. stop_reason이 여전히 tool_use인 동안 도구를 실행하고 결과를 돌려보내고 다시 요청하기를, end_turn으로 바뀔 때까지 반복한다. | How tool use works — Claude API |
| 데이터 의존 (data dependency) | 한 배치의 병렬 도구 호출 안에서, 한 호출의 파라미터가 이론상 다른 호출의 반환값과 같아야 하는 상황이다. 그 값은 배치가 생성되는 시점에 아직 존재하지 않는다. | Parallel tool use — Claude API |
| disable_parallel_tool_use | 요청의 tool_choice 객체에 두는 설정이다. true로 두면 모델은 응답 하나당 도구를 최대 하나만 호출하며, 병렬 호출 의존 관계가 아직 정리되지 않았을 때 동작을 조이는 데 쓴다. | Parallel tool use — Claude API |
| 영향 반경 (blast radius) | 도구 호출 하나가 잘못됐을 때 일으킬 수 있는 피해의 범위다. 다섯 가지 도구 유형의 순위를 매기는 핵심 기준이다. | Configure the sandboxed Bash tool - Claude Code Docs |
| read_file | 읽기 유형 도구를 가리키는 코스의 예시 이름이다. 전형적인 파라미터는 파일 경로이고, 파일 내용을 반환한다. | Tools reference — Claude Code Docs |
| write_file | 쓰기 유형 도구를 가리키는 코스의 예시 이름이다. 전형적인 파라미터는 경로와 내용이며, 실행되면 원본 파일을 덮어쓰고 대개 되돌릴 수 없다. | Tools reference — Claude Code Docs |
| bash | 실행 유형 도구를 가리키는 코스의 예시 이름이다. 파라미터는 어떤 셸 명령이든 실행할 수 있는 열린 명령 문자열이다. | Configure the sandboxed Bash tool - Claude Code Docs |
| search_code | 검색 유형 도구를 가리키는 코스의 예시 이름이다. 전형적인 파라미터로 pattern과 max_results가 있고, 파일 전체 내용이 아니라 일치 위치 목록을 반환한다. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| send_slack_message | 외부 API 호출 유형 도구를 가리키는 코스의 예시 이름이다. 전형적인 파라미터는 채널과 텍스트이며, 호출하면 네트워크를 건너 여러분이 통제하지 못하는 서비스로 간다. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| command | 실행 유형 도구(bash 같은)의 핵심 파라미터 필드다. 본질적으로 열린 셸 스크립트이며, 그 능력이 스키마 구조로 경계 지어지지 않는다. | Configure the sandboxed Bash tool - Claude Code Docs |
| max_results | 검색 유형 도구의 흔한 파라미터다. 한 번의 호출에서 돌아오는 일치 개수에 상한을 두어, 결과 과부하가 컨텍스트를 날려 버리는 것을 막는다. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 읽기 도구와 쓰기 도구의 비대칭 (asymmetry between read tools and write tools) | 읽기와 쓰기 도구는 호출 형태가 비슷하지만, 잘못된 읽기는 다시 읽으면 그만인 반면 잘못된 쓰기는 대개 되돌릴 수 없다. 두 위험의 결과는 등가가 아니다. | Tools reference — Claude Code Docs |
| retry_after | 외부 API 도구가 실패 시 반환할 수 있는 필드로, 재시도 전에 얼마나 기다려야 하는지 모델에게 알려 준다. '실패 정보는 행동 가능한 단서를 실어야 한다'의 구체적 예다. | Tools - Model Context Protocol |
| total_matches | search_code 도구의 반환 결과에 담기는 필드로, 전체 히트 수를 알려 준다. 모델이 결과가 완전한지 아니면 검색을 더 좁혀야 하는지 판단하게 해 준다. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| code_search_grep | 코스의 비교 예시에서 다시 쓴 검색 도구 이름이다. 내용으로 검색한다는 점을 description에 분명히 밝히고, 이름으로 파일을 찾을 때 쓸 도구로 code_search_glob을 지목한다. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| code_search_glob | code_search_grep과 짝을 이루는 파일 이름 조회 도구다. 코스는 이것으로, description에서 대안 도구를 지목하면 모델이 잘못된 도구를 고를 확률이 뚜렷이 낮아진다는 것을 보여 준다. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| enum | 파라미터의 값을 나열된 선택지 집합 중 하나로 좁히는 JSON Schema 키워드다. 단순한 메모가 아니라 유효하지 않은 입력을 거부하는 진짜 제약이다. | Creating your first schema - JSON Schema |
| additionalProperties: false | input_schema 최상위 설정으로, 입력 객체가 properties에 선언된 키만 지니도록 요구한다. 모델이 지어낸 여분의 필드가 하위 코드로 슬쩍 흘러 들어가는 틈을 닫는다. | Strict tool use — Claude API |
| strict 모드 (strict mode) | 도구 정의에 strict: true를 설정하면, 플랫폼이 모델의 샘플링을 제약해 생성되는 입력이 input_schema와 엄격히 일치하게 만들고, 유효하지 않은 파라미터는 애초에 생성되지 않는다. | Strict tool use — Claude API |
| 네임스페이싱 (namespacing) | 도구 이름에 서비스 접두사(github_, slack_ 같은)를 붙이는 관행이다. 도구가 많아질수록 모델이 접두사로 관련 없는 선택지를 먼저 배제할 수 있게 한다. | How to implement tool use - Claude Platform Docs |
| github_list_prs | 네임스페이싱된 도구 이름의 코스 예시다. github_ 접두사가 이 도구를 GitHub 서비스 소속으로 표시해, 다른 서비스의 같은 이름 작업과 구별하도록 돕는다. | How to implement tool use - Claude Platform Docs |
| slack_send_message | 코스의 또 다른 네임스페이싱된 도구 이름 예시다. slack_ 접두사가 이 도구를 Slack 서비스 소속으로 표시해, 다른 메시지 발송 도구와 구별한다. | How to implement tool use - Claude Platform Docs |
| title | 파라미터에 사람이 읽을 제목을 붙이는 JSON Schema의 서술 필드다. description과 마찬가지로 설명만 할 뿐 아무런 강제 제약을 부과하지 않는다. | Creating your first schema - JSON Schema |
| MCP | 클라이언트와 도구 서비스가 상호작용하는 방식을 정의하는 프로토콜이다. 코스는 모델이 스스로 교정할 수 있도록 오류 메시지를 모델에게 전달하라는 MCP의 명시적 요구를 인용한다. | Tools - Model Context Protocol |
| 55K 토큰 (55K tokens) | Anthropic 엔지니어링 팀이 든 예시 수치다. 도구 58개의 정의가 약 55K 토큰의 컨텍스트를 차지할 수 있으며, 이는 도구 개수가 컨텍스트 오버헤드에 미치는 실제 영향을 보여 준다. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 134K 토큰 (134K tokens) | 코스가 인용하는 더 극단적인 사례다. 도구 개수가 계속 늘어나면 도구 정의만으로 소비되는 컨텍스트가 매우 상당한 규모로 부풀 수 있음을 보여 준다. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| file_type | description이 제약이 아님을 보이려고 코스가 쓰는 예시 파라미터 필드다. description만으로는 모델이 임의의 값을 채울 수 있고, enum만이 실제로 값을 좁힌다. | Creating your first schema - JSON Schema |
| 세분성 (granularity) | 도구의 책임이 얼마나 잘게 나뉘어 있는가다. 코스는 세분성이 굵을수록도 잘을수록도 좋은 것이 아니라고 강조한다. 먼저 기능별로 쪼갠 뒤, 네임스페이싱과 description으로 잘못 고를 확률을 통제한다. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| 프롬프트 인젝션 (prompt injection) | 에이전트가 언젠가 읽게 될 콘텐츠(이슈, 웹 페이지)에 지시를 숨겨, 에이전트가 그 텍스트를 반드시 따라야 할 새 지시로 착각하게 만드는 공격이다. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| allow | 세 가지 권한 규칙 등급 중 하나다. 읽기 전용이고 부수 효과가 없으며 흔적을 남기지 않고 몇 번이든 반복할 수 있는 작업에 적용되고, 사람의 확인 없이 자동 승인된다. | Configure permissions - Claude Code Docs |
| ask | 세 가지 권한 규칙 등급 중 하나다. 부수 효과가 있지만 되돌릴 수 있고 영향 반경이 로컬 저장소 안에 머무는 작업에 적용되며, 실행 전에 사람의 확인을 요구한다. | Configure permissions - Claude Code Docs |
| deny | 세 가지 권한 규칙 등급 중 하나다. 되돌릴 수 없거나 영향 반경이 로컬을 넘는 작업에 적용되어 실행을 거부하며, ask와 allow보다 먼저 평가된다. | Configure permissions - Claude Code Docs |
| Read(./.env) | 코스의 구체적 권한 규칙 예시다. .env 파일을 읽는 작업을 곧장 deny 목록에 올려, 비밀 내용이 대화 컨텍스트로 들어오지 못하게 한다. | Configure permissions - Claude Code Docs |
| Bash(git push:*) | 코스의 권한 규칙 예시다. Tool(specifier) 형식이 호스트가 모델에게 노출하는 정확한 도구 이름과 호출 범위에 그대로 대응함을 보여 준다. | Configure permissions - Claude Code Docs |
| 과도한 행위성 (excessive agency) | 모델의 예상 밖이거나 모호하거나 조작된 출력이, 애초에 일어나서는 안 되었을 파괴적 동작을 촉발하는 것을 가리키는 OWASP의 위험 범주다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 과도한 기능 (Excessive functionality) | 과도한 행위성의 한 근본 원인이다. 도구 하나가 여러 역할을 겸해(가령 받은 편지함을 읽는 것과 메일을 내보내는 것을 모두 할 수 있어), 잘못된 호출 한 번의 영향 반경이 증폭된다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 과도한 권한 (Excessive permissions) | 과도한 행위성의 한 근본 원인이다. 도구 자체는 한 가지 일만 하지만, 부여된 접근 범위가 과제에 실제로 필요한 것을 넘어선다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 과도한 자율성 (Excessive autonomy) | 과도한 행위성의 한 근본 원인이다. 에이전트가 중간에 사람의 점검 없이 여러 단계를 연달아 실행해, 문제를 알아챘을 때는 되돌릴 수 없는 동작이 이미 실행된 뒤일 수 있다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 치명적 3요소 (lethal trifecta) | 비공개 데이터에 대한 접근, 신뢰할 수 없는 콘텐츠에 대한 노출, 외부와 통신할 능력이 한꺼번에 존재할 때 형성되는 위험 조합으로, 프롬프트 인젝션에 데이터를 실어 내보낼 경로를 준다. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| 사람 개입 통제 (human-in-the-loop) | 과도한 행위성에 대한 OWASP의 완화책 중 하나다. 영향이 큰 동작은 실행되기 전에 사람이 승인해야 한다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| 샌드박스 (sandbox) | 모델의 판단과 무관하게 파일 시스템 격리와 네트워크 격리를 강제하는 OS 수준 격리 메커니즘이다. 프롬프트 인젝션이 성공하더라도 피해가 갇혀 있게 한다. | Configure the sandboxed Bash tool - Claude Code Docs |
| TOOLS | 코스 예시에서 각 도구의 스키마 필드와 실제 실행 핸들러가 한 테이블 안에 함께 사는 단일 객체다. 양쪽이 서로 어긋나는 것을 막는다. | Define tools — Claude API |
| toolSchemas | TOOLS 테이블에서 파생되어 모델에게 보내는 tools 파라미터 목록이다. name/description/input_schema만 담고 핸들러는 담지 않는다. | Define tools — Claude API |
| toolHandlers | TOOLS 테이블에서 파생된 실행 시점 조회 테이블로, 각 도구 이름을 그것을 실제로 실행하는 함수에 대응시킨다. | How tool use works — Claude API |
| github_repo_info | 코스가 구현하는 세 번째 예시 도구다. 공개 GitHub 저장소의 기본 정보를 조회하며, 데이터를 프로젝트 밖으로 내보내는 유일한 도구다. | How to implement tool use - Claude Platform Docs |
| SAFE_NAME | owner/repo 파라미터의 형식을 검증하는 코스 코드의 정규식으로, 임의의 문자열이 외부 네트워크로 나가는 것을 막는다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| MAX_TURNS | 코스의 실행 루프에 두는 반복 상한으로, 모델이 도구 호출을 끝없이 요청해 루프가 종료되지 않는 것을 막는다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| PROJECT_ROOT | 프로젝트 루트 디렉터리를 담는 코스 코드의 상수다. read_file과 search_files가 모두 이것으로 경로 경계 검사를 해, 프로젝트 밖 파일 접근을 막는다. | Configure the sandboxed Bash tool - Claude Code Docs |
| recentCalls | 최근 몇 번의 도구 호출 서명을 기록하는 코스 코드의 배열로, '같은 도구가 같은 인자로 3회 연속 호출되는' 패턴을 감지하는 데 쓴다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| GITHUB_TOKEN | 환경 변수에서 읽는 선택적 자격 증명으로, GitHub API 호출 시 요청 한도를 높이는 데 쓴다. 이것 없이 익명으로도 호출은 동작한다. | Configure permissions - Claude Code Docs |
| 안전장치 (safety valve) | 실행 루프에 덧붙이는 보호 장치 묶음 — MAX_TURNS, 반복 호출 감지, 도구 내부의 경로·형식 검사 — 을 코스가 통틀어 부르는 말이다. 각각이 서로 다른 폭주 시나리오를 막는다. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| function walk(dir) | 코스 코드가 직접 구현하는 디렉터리 순회 함수로, searchFiles 안에서 grep을 셸로 호출하는 대신 파일을 재귀적으로 나열하는 데 쓴다. | Configure the sandboxed Bash tool - Claude Code Docs |
| JSON Schema | 도구의 input_schema를 정의하는 데 쓰는 명세다. title/description은 의도를 진술할 뿐 아무 제약을 더하지 않고, enum과 required 같은 키워드가 실제로 값을 검증한다. | Creating your first schema - JSON Schema |
| 문법 제약 샘플링 (grammar-constrained sampling) | strict 모드 뒤에 있는 기법이다. 플랫폼이 모델의 토큰 샘플링을 스키마에 유효한 출력으로 제약해, 생성되는 도구 입력이 언제나 JSON Schema와 일치하게 한다. | Strict tool use — Claude API |
| tool_choice | 모델이 도구를 어떻게 고르는지 제어하는 요청 객체다. 여기에 disable_parallel_tool_use: true를 두면(type이 auto일 때) 모델은 응답 하나당 도구를 최대 하나만 호출한다. | Parallel tool use — Claude API |