에이전트 정의하기

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

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

에이전트 구성 필드

에이전트를 변경하지 않고 단일 세션에 대해 model, system, tools, mcp_servers, skills를 재정의할 수도 있습니다. model 재정의는 에이전트의 model 객체를 전체적으로 대체하므로, 에이전트 자체의 effort는 이어지지 않습니다. 특정 effort 수준으로 세션을 실행하려면 재정의의 model 객체 안에 effort를 설정하세요. 세션에 대한 에이전트 구성 재정의하기를 참조하세요.

에이전트 생성하기

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

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

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-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-5",
    "effort": { "type": "medium" },
    "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-5
  inference_geo: us
---

You are a helpful assistant.

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

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

에이전트 업데이트하기

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

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

ant apply coding-assistant.md

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

You are a helpful coding agent. Always write tests.

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

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

업데이트 의미 체계

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

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

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

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

• multiagent는 업데이트가 multiagent_20261001 유형을 유지하는 경우 저장된 블록에 수준별로 병합됩니다. 생략한 설정은 저장된 값을 유지하며, 전송한 predefined_agents 목록은 저장된 목록을 대체합니다. multiagent를 전송하는 그 밖의 업데이트는 저장된 블록 전체를 대체하며, 생략된 설정은 기본값을 갖습니다. 블록 전체를 지우려면 multiagent=None을 전달하세요. 블록 내부에서 null은 설정을 기본값으로 재설정하므로, workflows를 null로 설정하면 동적 워크플로가 켜집니다. 동적 워크플로 켜기를 참조하세요.

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

• 변경 없음 감지. 업데이트가 현재 버전과 비교하여 아무런 변경도 만들지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다.

• 다른 에이전트의 predefined_agents 목록은 업데이트되지 않습니다. subagents 또는 workflows의 predefined_agents 목록에 이 에이전트를 나열한 에이전트는, 참조에서 version을 생략하더라도 생성 시점 또는 업데이트가 마지막으로 해당 목록을 전송한 시점에 고정된 버전을 유지합니다. 새 버전에 위임하려면 목록이 새 버전을 참조하도록 해당 에이전트를 나열한 에이전트를 업데이트하세요.

다음 업데이트는 설명을 지우고, metadata에서 team 키를 삭제하며, workflows를 null로 설정하여 동적 워크플로를 켭니다:

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

에이전트 수명 주기

버전 목록 조회

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

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

에이전트 보관하기

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

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

다음 단계