에이전트 정의하기

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

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



에이전트 구성 필드

에이전트를 변경하지 않고 단일 세션에 대해 model, system, tools, mcp_servers, skills를 재정의할 수도 있습니다. 세션에 대한 에이전트 구성 재정의를 참조하세요.



에이전트 생성

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

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

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

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

응답은 구성을 그대로 반환하며 id, type, version, created_at, updated_at, archived_at 필드를 추가합니다. version은 1에서 시작하여 업데이트로 에이전트가 변경될 때마다 증가합니다.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "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
}

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



에이전트 업데이트

에이전트를 업데이트하면 구성이 변경될 때 새 버전이 생성됩니다. version 필드는 필수이며 에이전트의 현재 버전과 일치해야 하므로, 항상 알려진 상태에서 업데이트하게 됩니다. 버전이 일치하지 않으면 409가 반환되며, 아카이브된 에이전트에 대한 업데이트는 거부됩니다.

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



업데이트 의미론

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

• 스칼라 필드(model, system, name, description)는 새 값으로 대체됩니다. system과 description은 null을 전달하여 지울 수 있습니다. model과 name은 필수이며 지울 수 없습니다.

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

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

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

• 무변경 감지. 업데이트가 현재 버전과 비교하여 변경 사항을 생성하지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다.

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



에이전트 수명 주기



버전 목록 조회

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

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



에이전트 아카이브

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

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



다음 단계