에이전트 정의하기

에이전트는 페르소나와 기능을 정의하는 재사용 가능하고 버전이 관리되는 구성입니다. 에이전트는 세션 중 Claude가 어떻게 동작할지를 결정하는 모델, "system prompt"(시스템 프롬프트), 도구, MCP 서버, 스킬을 하나로 묶습니다.

에이전트를 재사용 가능한 리소스로 한 번 생성한 뒤, 세션을 시작할 때마다 ID로 참조하세요. 에이전트는 버전이 관리되며 여러 세션에 걸쳐 관리하기가 더 쉽습니다.

에이전트 구성 필드

에이전트를 변경하지 않고 단일 세션에 대해 model, system, tools, mcp_servers, skills를 재정의할 수도 있습니다. 세션별 model 재정의 내부에 설정된 effort 수준은 적용되지 않으며, 재정의가 에이전트의 model 객체를 통째로 대체하기 때문에 model 재정의로 생성된 세션은 모델의 기본 effort 수준으로 실행됩니다. 특정 effort 수준으로 실행하려면 에이전트에 effort를 설정하고 해당 세션에서 model을 재정의하지 마세요. 세션에 대한 에이전트 구성 재정의를 참조하세요.

에이전트 생성

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

예제는 curl, ant CLI 또는 SDK 중 하나를 사용합니다. 아직 설정하지 않았다면 빠른 시작에서 설치 및 클라이언트 설정을 다룹니다.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

응답은 구성을 그대로 반환하면서 id, type, version, created_at, updated_at, archived_at 필드를 추가하고, effort와 같이 생략한 model 필드를 기본값으로 채웁니다. version은 1에서 시작하며 업데이트로 에이전트가 변경될 때마다 증가합니다.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5",
    "effort": { "type": "high" },
    "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": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

도구 세트의 default_config는 기본 권한 정책인 always_allow를 보여주며, 별도로 구성하지 않는 한 이 정책이 적용됩니다.

추론 지역 고정하기

speed 및 effort와 마찬가지로 inference_geo는 model의 객체 형식을 통해 설정합니다. model을 객체로 전달하고 id와 함께 inference_geo를 설정하세요. 이 필드는 "us" 또는 "global"을 받습니다. 설정하지 않으면 각 모델 요청은 처리되는 시점의 워크스페이스 기본 추론 지역을 따릅니다. 워크스페이스 수준의 지역 제어 및 가격은 데이터 레지던시를 참조하세요.

다음 예제는 에이전트를 미국 추론으로 고정하고 에이전트의 model 객체에서 inference_geo 값을 출력합니다:

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5
  inference_geo: us
---

You are a helpful assistant.

inference_geo 고정은 에이전트가 저장될 때, 에이전트로부터 세션이 생성될 때, 그리고 세션이 처리하는 모든 턴마다 워크스페이스의 allowed_inference_geos에 대해 검증됩니다. 워크스페이스 허용 목록이 좁아져 고정 값이 더 이상 허용되지 않으면, 해당 에이전트로부터 새 세션을 생성할 수 없고 실행 중인 세션은 추가 턴을 거부합니다. 워크스페이스가 규정 준수 및 데이터 레지던시를 위해 고정에 의존하기 때문에 고정은 절대 예외 처리되지 않습니다.

지리적 추론 고정을 지원하지 않는 모델에 inference_geo를 설정하면 400 오류가 반환됩니다. 지원하는 모델은 모델 가용성을 참조하세요. multiagent 구성에서는 코디네이터의 고정 값과 모든 로스터 구성원의 고정 값이 모두 동일한 값으로 설정되거나 모두 설정되지 않아야 합니다. 멀티에이전트 오케스트레이션을 참조하세요. 나중에 고정을 변경하거나 해제하려면 에이전트의 model 객체를 업데이트하세요. 업데이트 의미론에 설명된 대로 inference_geo 없이 model을 제공하면 고정이 해제됩니다.

에이전트 업데이트

에이전트를 업데이트하면 구성이 변경될 때 새 버전이 생성됩니다. version 필드는 선택 사항입니다. 낙관적 동시성 제어를 위해 제공하거나(불일치 시 409 반환), 생략하여 업데이트를 무조건 적용할 수 있습니다(마지막 쓰기 우선). 아카이브된 에이전트에 대한 업데이트는 거부됩니다.

CLI를 사용하는 경우 에이전트 파일을 편집하고 ant apply를 다시 실행하세요. apply가 version을 자동으로 제공합니다.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

앞의 예제는 생성 응답에서 받은 version을 제공하므로, 읽은 이후 다른 곳에서 에이전트를 변경하지 않은 경우에만 업데이트가 적용됩니다. 업데이트를 무조건 적용하려면 요청에서 version을 생략하세요:

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 '{
    "description": "Writes and reviews code."
  }')

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

업데이트 의미론

• version은 선택 사항이며 제공할 경우 최소 1이어야 합니다. 제공된 경우, 보낸 필드가 이미 저장된 값과 일치하더라도 에이전트의 현재 버전과 일치하지 않으면 요청은 409를 반환합니다. 에이전트를 다시 읽고 재시도하세요. 생략된 경우 업데이트는 무조건 적용되며, 가장 최근의 업데이트가 동시에 발생한 다른 업데이트를 어느 호출자에게도 오류 없이 조용히 대체합니다. 대화형 호출자에게는 version을 제공하는 것이 권장되는 기본값이며, 체크인된 에이전트 정의를 동기화하는 CI 작업처럼 루프가 에이전트를 소유하는 선언적 적용 루프에는 생략하는 것이 적합합니다.

• 생략된 필드는 보존됩니다. 변경하려는 필드만 포함하면 됩니다.

• 스칼라 필드(model, system, name, description)는 새 값으로 대체됩니다. system과 description은 null을 전달하여 지울 수 있습니다. model과 name은 필수이며 지울 수 없습니다. 제공하는 model 객체 내에서 effort는 유일한 예외입니다. 모델 id가 변경되지 않은 경우 effort를 생략하면 저장된 effort 수준이 그대로 유지됩니다. 모델 id를 변경하면 생략된 effort는 새 모델의 기본값으로 재설정됩니다. 다른 model 필드는 객체와 함께 대체됩니다. inference_geo 없이 model을 제공하면 에이전트의 추론 지역 고정이 해제됩니다.

• 배열 필드(tools, mcp_servers, skills)는 새 배열로 완전히 대체됩니다. 배열 필드를 완전히 지우려면 null 또는 빈 배열을 전달하세요.

• multiagent는 agents 로스터를 포함하여 전체가 대체됩니다. 지우려면 null을 전달하세요.

• 메타데이터는 키 수준에서 병합됩니다. 제공한 키는 추가되거나 업데이트됩니다. 생략한 키는 보존됩니다. 특정 키를 삭제하려면 해당 값을 null로 설정하세요.

• No-op 감지. 업데이트가 현재 버전 대비 아무런 변경도 만들지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다.

• 코디네이터 로스터는 업데이트되지 않습니다. multiagent.agents 로스터에서 이 에이전트를 참조하는 코디네이터는 참조에서 version을 생략했더라도 코디네이터가 생성되거나 마지막으로 업데이트되었을 때 고정된 버전을 유지합니다. 새 버전에 위임하려면 로스터가 새 버전을 참조하도록 코디네이터를 업데이트하세요.

에이전트 수명 주기

버전 목록 조회

전체 버전 기록을 가져와 에이전트가 시간에 따라 어떻게 변경되었는지 추적하세요. 결과는 페이지로 나뉘며, SDK 예제는 모든 페이지를 자동으로 가져옵니다.

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

에이전트 아카이브

아카이브는 에이전트를 읽기 전용으로 만들며 되돌릴 수 없습니다. 기존 세션은 계속 실행되지만 새 세션은 해당 에이전트를 참조할 수 없습니다. 응답은 archived_at을 아카이브 타임스탬프로 설정합니다.

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

다음 단계