LLM Wiki

Claude Managed Agents — 내장 도구와 커스텀 도구

3 min read

Claude Managed Agents — 내장 도구와 커스텀 도구

Managed Agents 심층 학습 노트의 도구 편. agent_toolset_20260401 내장 도구 구성과 커스텀 도구 정의 및 베스트 프랙티스를 다룬다.

6. 내장 도구 (Built-in Tools)

agent_toolset_20260401 타입 지정 시 아래 도구가 기본 활성화.

도구이름설명
Bashbash쉘 명령 실행
Readread파일 읽기
Writewrite파일 쓰기
Editedit파일 문자열 치환
Globglob파일 패턴 매칭
Grepgrep정규식 텍스트 검색
Web fetchweb_fetchURL에서 콘텐츠 가져오기
Web searchweb_search웹 검색

6.1 특정 도구 비활성화

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    tools=[{
        "type": "agent_toolset_20260401",
        "configs": [
            {"name": "web_fetch", "enabled": False},
            {"name": "web_search", "enabled": False},
        ],
    }],
)

6.2 일부 도구만 활성화 (화이트리스트 방식)

tools=[{
    "type": "agent_toolset_20260401",
    "default_config": {"enabled": False},  # 모든 도구 기본 비활성화
    "configs": [
        {"name": "bash", "enabled": True},
        {"name": "read", "enabled": True},
        {"name": "write", "enabled": True},
    ],
}]

7. 커스텀 도구 (Custom Tools)

Messages API의 사용자 정의 도구와 유사. Claude가 요청을 emit → 클라이언트 코드가 실행 → 결과를 Claude에게 반환.

agent = client.beta.agents.create(
    name="Weather Agent",
    model="claude-sonnet-4-6",
    tools=[
        {"type": "agent_toolset_20260401"},
        {
            "type": "custom",
            "name": "get_weather",
            "description": "특정 도시의 현재 날씨 조회. 날씨 관련 질문에만 사용.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "도시 이름"}
                },
                "required": ["location"],
            },
        },
    ],
)

커스텀 도구 베스트 프랙티스

  1. 극도로 상세한 description 작성 — 가장 중요한 요소. 언제 써야 하는지, 언제 쓰면 안 되는지, 각 파라미터의 의미와 동작에 미치는 영향, 중요한 제한사항까지 명시. 도구당 최소 3~4문장.
  2. 관련 작업은 하나의 도구로 통합 — create_pr, review_pr, merge_pr 대신 action 파라미터를 가진 단일 pull_request 도구로.
  3. 도구 이름에 네임스페이스 사용 — db_query, storage_read 등 리소스 접두사로 명확성 확보.
  4. 응답은 high-signal 정보만 — 의미 있는 안정적인 식별자(슬러그, UUID)만 반환. Claude가 다음 단계를 추론하는 데 필요한 필드만 포함.

그래프 뷰

백링크