에이전트 설정

빌드에이전트 정의

에이전트 정의

재사용 가능한 버전 관리 에이전트 구성을 만듭니다.

에이전트는 페르소나와 기능을 정의하는 재사용 가능한 버전 관리 구성입니다. 모델, 시스템 프롬프트, 도구, MCP 서버 및 Claude의 동작 방식을 형성하는 스킬을 번들로 제공합니다.

에이전트를 재사용 가능한 리소스로 한 번 만들고 세션을 시작할 때마다 ID로 참조합니다. 에이전트는 버전 관리되며 많은 세션에서 관리하기가 더 쉽습니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

에이전트 구성 필드

필드	설명
`name`	필수. 에이전트의 사람이 읽을 수 있는 이름입니다.
`model`	필수. 에이전트를 구동하는 Claude 모델입니다. Claude 4.5 이상의 모든 모델이 지원됩니다.
`system`	에이전트의 동작과 페르소나를 정의하는 시스템 프롬프트입니다. 시스템 프롬프트는 수행할 작업을 설명해야 하는 사용자 메시지와는 별개입니다.
`tools`	에이전트가 사용할 수 있는 도구입니다. 사전 구축된 에이전트 도구, MCP 도구 및 사용자 정의 도구를 결합합니다.
`mcp_servers`	표준화된 타사 기능을 제공하는 MCP 서버입니다.
`skills`	점진적 공개를 통해 도메인별 컨텍스트를 제공하는 스킬입니다.
`callable_agents`	이 에이전트가 다중 에이전트 오케스트레이션을 위해 호출할 수 있는 다른 에이전트입니다. 이것은 연구 미리보기 기능입니다. 액세스를 요청하여 시도해보세요.
`description`	에이전트가 수행하는 작업에 대한 설명입니다.
`metadata`	자신의 추적을 위한 임의의 키-값 쌍입니다.

에이전트 만들기

다음 예제는 Claude Opus 4.7을 사용하고 사전 구축된 에이전트 도구 세트에 액세스할 수 있는 코딩 에이전트를 정의합니다. 도구 세트를 통해 에이전트는 코드를 작성하고, 파일을 읽고, 웹을 검색할 수 있습니다. 지원되는 도구의 전체 목록은 에이전트 도구 참조를 참조하세요.

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

Claude Opus 4.6을 빠른 모드와 함께 사용하려면 model을 객체로 전달합니다: {"id": "claude-opus-4-6", "speed": "fast"}.

응답은 구성을 반복하고 id, version, created_at, updated_at 및 archived_at 필드를 추가합니다. version은 1에서 시작하여 에이전트를 업데이트할 때마다 증가합니다.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-7",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

에이전트 업데이트

에이전트를 업데이트하면 새 버전이 생성됩니다. 현재 version을 전달하여 알려진 상태에서 업데이트하고 있는지 확인합니다.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."

업데이트 의미론

생략된 필드는 보존됩니다. 변경하려는 필드만 포함하면 됩니다.
스칼라 필드 (model, system, name 등)는 새 값으로 대체됩니다. system과 description은 null을 전달하여 지울 수 있습니다. model과 name은 필수이며 지울 수 없습니다.
배열 필드 (tools, mcp_servers, skills, callable_agents)는 새 배열로 완전히 대체됩니다. 배열 필드를 완전히 지우려면 null 또는 빈 배열을 전달합니다.
메타데이터는 키 수준에서 병합됩니다. 제공하는 키는 추가되거나 업데이트됩니다. 생략하는 키는 보존됩니다. 특정 키를 삭제하려면 해당 값을 빈 문자열로 설정합니다.
작동 없음 감지. 업데이트가 현재 버전에 비해 변경을 생성하지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다.

에이전트 수명 주기

작업	동작
업데이트	새 에이전트 버전을 생성합니다.
버전 나열	전체 버전 기록을 가져와 시간 경과에 따른 변경 사항을 추적합니다.
보관	에이전트가 읽기 전용이 됩니다. 새 세션은 이를 참조할 수 없지만 기존 세션은 계속 실행됩니다.

버전 나열

전체 버전 기록을 가져와 에이전트가 시간 경과에 따라 어떻게 변경되었는지 추적합니다.

ant beta:agents:versions list --agent-id "$AGENT_ID"

에이전트 보관

보관하면 에이전트가 읽기 전용이 됩니다. 기존 세션은 계속 실행되지만 새 세션은 에이전트를 참조할 수 없습니다. 응답은 archived_at을 보관 타임스탬프로 설정합니다.

ant beta:agents archive --agent-id "$AGENT_ID"

다음 단계

도구 구성하여 에이전트가 사용할 수 있는 기능을 사용자 정의합니다.
스킬 첨부하여 도메인별 전문 지식을 제공합니다.
세션 시작하여 에이전트를 참조합니다.

Was this page helpful?

빌드에이전트 정의

에이전트 정의

재사용 가능한 버전 관리 에이전트 구성을 만듭니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

에이전트 구성 필드

필드	설명
`name`	필수. 에이전트의 사람이 읽을 수 있는 이름입니다.
`model`	필수. 에이전트를 구동하는 Claude 모델입니다. Claude 4.5 이상의 모든 모델이 지원됩니다.
`system`	에이전트의 동작과 페르소나를 정의하는 시스템 프롬프트입니다. 시스템 프롬프트는 수행할 작업을 설명해야 하는 사용자 메시지와는 별개입니다.
`tools`	에이전트가 사용할 수 있는 도구입니다. 사전 구축된 에이전트 도구, MCP 도구 및 사용자 정의 도구를 결합합니다.
`mcp_servers`	표준화된 타사 기능을 제공하는 MCP 서버입니다.
`skills`	점진적 공개를 통해 도메인별 컨텍스트를 제공하는 스킬입니다.
`callable_agents`	이 에이전트가 다중 에이전트 오케스트레이션을 위해 호출할 수 있는 다른 에이전트입니다. 이것은 연구 미리보기 기능입니다. 액세스를 요청하여 시도해보세요.
`description`	에이전트가 수행하는 작업에 대한 설명입니다.
`metadata`	자신의 추적을 위한 임의의 키-값 쌍입니다.

에이전트 만들기

ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-7}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}'

Claude Opus 4.6을 빠른 모드와 함께 사용하려면 model을 객체로 전달합니다: {"id": "claude-opus-4-6", "speed": "fast"}.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-7",
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

에이전트 업데이트

에이전트를 업데이트하면 새 버전이 생성됩니다. 현재 version을 전달하여 알려진 상태에서 업데이트하고 있는지 확인합니다.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."

업데이트 의미론

생략된 필드는 보존됩니다. 변경하려는 필드만 포함하면 됩니다.
스칼라 필드 (model, system, name 등)는 새 값으로 대체됩니다. system과 description은 null을 전달하여 지울 수 있습니다. model과 name은 필수이며 지울 수 없습니다.
배열 필드 (tools, mcp_servers, skills, callable_agents)는 새 배열로 완전히 대체됩니다. 배열 필드를 완전히 지우려면 null 또는 빈 배열을 전달합니다.
메타데이터는 키 수준에서 병합됩니다. 제공하는 키는 추가되거나 업데이트됩니다. 생략하는 키는 보존됩니다. 특정 키를 삭제하려면 해당 값을 빈 문자열로 설정합니다.
작동 없음 감지. 업데이트가 현재 버전에 비해 변경을 생성하지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다.

에이전트 수명 주기

작업	동작
업데이트	새 에이전트 버전을 생성합니다.
버전 나열	전체 버전 기록을 가져와 시간 경과에 따른 변경 사항을 추적합니다.
보관	에이전트가 읽기 전용이 됩니다. 새 세션은 이를 참조할 수 없지만 기존 세션은 계속 실행됩니다.

버전 나열

전체 버전 기록을 가져와 에이전트가 시간 경과에 따라 어떻게 변경되었는지 추적합니다.

ant beta:agents:versions list --agent-id "$AGENT_ID"

에이전트 보관

ant beta:agents archive --agent-id "$AGENT_ID"

다음 단계

도구 구성하여 에이전트가 사용할 수 있는 기능을 사용자 정의합니다.
스킬 첨부하여 도메인별 전문 지식을 제공합니다.
세션 시작하여 에이전트를 참조합니다.

Was this page helpful?