에이전트 정의하기

에이전트는 페르소나와 기능을 정의하는 재사용 가능하고 버전 관리되는 구성입니다. 세션 중 Claude의 동작 방식을 결정하는 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 묶어 제공합니다.

에이전트를 재사용 가능한 리소스로 한 번 생성하고, 세션을 시작할 때마다 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 Sonnet 4.6을 사용하는 코딩 에이전트를 정의합니다. 툴셋을 통해 에이전트는 코드 작성, 파일 읽기, 웹 검색 등을 수행할 수 있습니다. 지원되는 도구의 전체 목록은 에이전트 도구 참조를 참조하세요.

빠른 모드와 함께 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-sonnet-4-6",
    "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을 전달하세요.

업데이트 의미론

생략된 필드는 보존됩니다. 변경하려는 필드만 포함하면 됩니다.
스칼라 필드 (model, system, name 등)는 새 값으로 대체됩니다. system과 description은 null을 전달하여 지울 수 있습니다. model과 name은 필수이며 지울 수 없습니다.
배열 필드 (tools, mcp_servers, skills, callable_agents)는 새 배열로 완전히 대체됩니다. 배열 필드를 완전히 지우려면 null 또는 빈 배열을 전달하세요.

에이전트 수명 주기

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

버전 목록

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

에이전트 아카이브

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

다음 단계

도구 구성으로 에이전트가 사용할 수 있는 기능을 커스터마이즈하세요.
도메인별 전문 지식을 위해 스킬 연결을 하세요.
에이전트를 참조하는 세션 시작을 하세요.

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"