--- title: 에이전트 정의하기 url: https://platform.claude.com/docs/ko/managed-agents/agent-setup description: 재사용 가능하고 버전 관리되는 에이전트 구성을 생성합니다. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 에이전트는 페르소나와 기능을 정의하는 재사용 가능하고 버전 관리되는 구성입니다. 에이전트는 세션 중 Claude의 동작 방식을 결정하는 모델, 시스템 프롬프트, 도구, MCP 서버, 스킬을 하나로 묶습니다. 에이전트를 재사용 가능한 리소스로 한 번 생성한 다음, [세션을 시작](https://platform.claude.com/docs/ko/managed-agents/sessions)할 때마다 ID로 참조하세요. 에이전트는 버전 관리되며 여러 세션에 걸쳐 관리하기가 더 쉽습니다. ## 에이전트 구성 필드 | 필드 | 설명 | | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` (csharp, go: `Name`) | 필수. 사람이 읽을 수 있는 에이전트 이름입니다. | | `model` (csharp, go: `Model`) | 필수. 에이전트를 구동하는 Claude [모델](https://platform.claude.com/docs/ko/models/overview)입니다. 모델 ID 문자열 또는 객체(예: `{"id": "claude-opus-5-5"}`)를 받습니다. Claude 4.5 이상 모델이 지원됩니다. 객체 형식은 `speed`, `effort`, `inference_geo` 필드도 받습니다. [에이전트 생성하기](https://platform.claude.com/docs/ko/managed-agents/agent-setup#create-an-agent)의 팁, [Effort 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#effort-levels), [추론 지역 고정하기](https://platform.claude.com/docs/ko/managed-agents/agent-setup#pin-the-inference-geo)를 참조하세요. | | `system` (csharp, go: `System`; ruby: `system_`) | 에이전트의 동작과 페르소나를 정의하는 [시스템 프롬프트](https://platform.claude.com/docs/ko/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role)입니다. 시스템 프롬프트는 수행할 작업을 설명해야 하는 [사용자 메시지](https://platform.claude.com/docs/ko/managed-agents/reference#event-types)와는 구별됩니다. | | `tools` (csharp, go: `Tools`) | 에이전트가 사용할 수 있는 도구입니다. [사전 구축된 에이전트 도구](https://platform.claude.com/docs/ko/managed-agents/tools), [MCP 도구](https://platform.claude.com/docs/ko/managed-agents/mcp-connector), [사용자 정의 도구](https://platform.claude.com/docs/ko/managed-agents/tools#custom-tools)를 결합합니다. | | `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | 표준화된 서드파티 기능을 제공하는 [MCP 서버](https://platform.claude.com/docs/ko/managed-agents/mcp-connector)입니다. | | `skills` (csharp, go: `Skills`) | "progressive disclosure"(점진적 공개) 방식으로 도메인별 컨텍스트를 제공하는 [스킬](https://platform.claude.com/docs/ko/managed-agents/skills)입니다. | | `multiagent` (csharp, go: `Multiagent`) | 에이전트가 서브에이전트로 또는 [동적 워크플로](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#dynamic-workflows)에서 다른 에이전트에게 작업을 넘길 수 있게 하며, 선택적으로 [어드바이저](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#give-the-session-an-advisor) 모델에 자문을 구할 수 있게 합니다. `multiagent_20261001` 유형에서는 비활성화하지 않는 한 동적 워크플로가 켜져 있습니다. [멀티에이전트 오케스트레이션](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration)을 참조하세요. | | `description` (csharp, go: `Description`) | 에이전트가 수행하는 작업에 대한 설명입니다. | | `metadata` (csharp, go: `Metadata`) | 자체 추적을 위한 임의의 키-값 쌍입니다. | 에이전트를 변경하지 않고 단일 세션에 대해 `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`)를 재정의할 수도 있습니다. `model` (csharp, go: `Model`) 재정의는 에이전트의 `model` (csharp, go: `Model`) 객체를 전체적으로 대체하므로, 에이전트 자체의 `effort` (csharp, go: `Effort`)는 이어지지 않습니다. 특정 effort 수준으로 세션을 실행하려면 재정의의 `model` (csharp, go: `Model`) 객체 안에 `effort` (csharp, go: `Effort`)를 설정하세요. [세션에 대한 에이전트 구성 재정의하기](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)를 참조하세요. ## 에이전트 생성하기 다음 예제는 최신 Claude Opus 모델을 사용하고 사전 구축된 에이전트 도구 세트에 접근할 수 있는 코딩 에이전트를 정의합니다. 이 도구 세트를 통해 에이전트는 코드 작성, 파일 읽기, 웹 검색 등을 수행할 수 있습니다. 지원되는 도구의 전체 목록은 [에이전트 도구 레퍼런스](https://platform.claude.com/docs/ko/managed-agents/tools)를 참조하세요. 예제는 curl, `ant` CLI 또는 SDK 중 하나를 사용합니다. 아직 설정하지 않았다면 [빠른 시작](https://platform.claude.com/docs/ko/managed-agents/quickstart#install-the-cli)에서 설치 및 클라이언트 설정을 다룹니다. ```bash cURL 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-opus-5-5", "system": "You are a helpful coding agent.", "tools": [{"type": "agent_toolset_20260401"}] }' ``` ```bash CLI ant apply coding-assistant.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful coding agent. ``` [`ant apply`](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply)는 `coding-assistant.md`로부터 에이전트를 생성하고, 해당 ID를 출력하며, 이를 `claude-lock.json`에 기록합니다. 다음 `ant apply`가 두 번째 에이전트를 생성하는 대신 이 에이전트를 업데이트하도록 `claude-lock.json`을 커밋하세요. ```python Python agent = client.beta.agents.create( name="Coding Assistant", model="claude-opus-5-5", system="You are a helpful coding agent.", tools=[ {"type": "agent_toolset_20260401"}, ], ) ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Coding Assistant", model: "claude-opus-5-5", system: "You are a helpful coding agent.", tools: [{ type: "agent_toolset_20260401" }], }); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Coding Assistant", Model = BetaManagedAgentsModel.ClaudeOpus5_5, System = "You are a helpful coding agent.", Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401", }, ], }); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Coding Assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, }, System: anthropic.String("You are a helpful coding agent."), Tools: []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }}, }) if err != nil { panic(err) } ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Coding Assistant") .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .system("You are a helpful coding agent.") .addTool( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build() ) .build() ); ``` ```php PHP $agent = $client->beta->agents->create( name: 'Coding Assistant', model: 'claude-opus-5-5', system: 'You are a helpful coding agent.', tools: [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', ), ], ); ``` ```ruby Ruby agent = client.beta.agents.create( name: "Coding Assistant", model: "claude-opus-5-5", system_: "You are a helpful coding agent.", tools: [{type: "agent_toolset_20260401"}] ) ``` 응답은 구성을 그대로 반환하면서 `id`, `type`, `version`, `created_at`, `updated_at`, `archived_at` 필드를 추가하고, `effort`처럼 생략한 `model` 필드를 기본값으로 채웁니다. `version`은 1부터 시작하며 업데이트로 에이전트가 변경될 때마다 증가합니다. ```json { "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`는 기본 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)인 `always_allow`를 보여 주며, 이는 별도로 구성하지 않는 한 적용됩니다. Claude Opus 5.5, Claude Opus 5 또는 Claude Opus 4.8을 [fast mode](https://platform.claude.com/docs/ko/build-with-claude/fast-mode)로 사용하려면 `model`을 객체로 전달하세요. 예: `{"id": "claude-opus-5-5", "speed": "fast"}`. fast mode 페이지의 [지원 모델](https://platform.claude.com/docs/ko/build-with-claude/fast-mode#supported-models)을 참조하세요. 모델의 effort 수준을 설정하려면 `model`을 객체로 전달하세요. 예: `{"id": "claude-opus-5-5", "effort": "high"}`. `effort` 필드는 수준 문자열(`low`, `medium`, `high`, `xhigh` 또는 `max`) 또는 `{"type": "high"}`와 같은 객체를 받습니다. 각 수준의 동작은 [Effort 수준](https://platform.claude.com/docs/ko/build-with-claude/effort#effort-levels)을 참조하세요. ### 추론 지역 고정하기 `speed` (csharp, go: `Speed`) 및 `effort` (csharp, go: `Effort`)와 마찬가지로, `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)는 `model` (csharp, go: `Model`)의 객체 형식을 통해 설정됩니다. `model` (csharp, go: `Model`)을 객체로 전달하고 `id` (csharp, go: `ID`)와 함께 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)를 설정하세요. 이 필드는 `"us"` 또는 `"global"`을 받습니다. 설정하지 않으면 각 모델 요청은 처리되는 시점의 워크스페이스 기본 추론 지역을 따릅니다. 워크스페이스 수준의 지역 제어 및 가격은 [데이터 레지던시](https://platform.claude.com/docs/ko/manage-claude/data-residency)를 참조하세요. 다음 예제는 에이전트를 미국 추론으로 고정하고 에이전트의 `model` (csharp, go: `Model`) 객체에서 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 값을 출력합니다: ```bash cURL 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": "Geo-pinned assistant", "model": {"id": "claude-opus-5-5", "inference_geo": "us"}, "system": "You are a helpful assistant." }' ``` ```bash CLI ant apply geo-pinned-assistant.md ``` ```markdown --- name: Geo-pinned assistant model: id: claude-opus-5-5 inference_geo: us --- You are a helpful assistant. ``` ```python Python agent = client.beta.agents.create( name="Geo-pinned assistant", model={ "id": "claude-opus-5-5", "inference_geo": "us", }, system="You are a helpful assistant.", ) print(f"Inference geo: {agent.model.inference_geo}") ``` ```typescript TypeScript const agent = await client.beta.agents.create({ name: "Geo-pinned assistant", model: { id: "claude-opus-5-5", inference_geo: "us" }, system: "You are a helpful assistant.", }); console.log(`Inference geo: ${agent.model.inference_geo}`); ``` ```csharp C# var agent = await client.Beta.Agents.Create(new() { Name = "Geo-pinned assistant", Model = new BetaManagedAgentsModelConfigParams { ID = BetaManagedAgentsModel.ClaudeOpus5_5, InferenceGeo = "us", }, System = "You are a helpful assistant.", }); Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}"); ``` ```go Go agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ Name: "Geo-pinned assistant", Model: anthropic.BetaManagedAgentsModelConfigParams{ ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5, InferenceGeo: anthropic.String("us"), }, System: anthropic.String("You are a helpful assistant."), }) if err != nil { panic(err) } fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo) ``` ```java Java var agent = client.beta().agents().create( AgentCreateParams.builder() .name("Geo-pinned assistant") .model( BetaManagedAgentsModelConfigParams.builder() .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5) .inferenceGeo("us") .build() ) .system("You are a helpful assistant.") .build() ); IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow()); ``` ```php PHP $agent = $client->beta->agents->create( name: 'Geo-pinned assistant', model: BetaManagedAgentsModelConfigParams::with( id: 'claude-opus-5-5', inferenceGeo: 'us', ), system: 'You are a helpful assistant.', ); echo "Inference geo: {$agent->model->inferenceGeo}\n"; ``` ```ruby Ruby agent = client.beta.agents.create( name: "Geo-pinned assistant", model: {id: "claude-opus-5-5", inference_geo: "us"}, system_: "You are a helpful assistant." ) puts "Inference geo: #{agent.model.inference_geo}" ``` `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 고정은 에이전트가 저장될 때, 에이전트로부터 세션이 생성될 때, 그리고 세션이 처리하는 모든 턴에서 워크스페이스의 [`allowed_inference_geos`](https://platform.claude.com/docs/ko/manage-claude/data-residency#workspace-level-restrictions)에 대해 검증됩니다. 워크스페이스 허용 목록이 좁아져 고정이 더 이상 허용되지 않으면, 해당 에이전트로부터 새 세션을 생성할 수 없고 실행 중인 세션은 이후 턴을 거부합니다. 워크스페이스는 규정 준수와 데이터 레지던시를 위해 고정에 의존하므로 고정은 절대 예외로 처리되지 않습니다. 지리적 추론 고정을 지원하지 않는 모델에 `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)를 설정하면 400 오류가 반환됩니다. 지원하는 모델은 [모델 가용성](https://platform.claude.com/docs/ko/manage-claude/data-residency#model-availability)을 참조하세요. `multiagent` (csharp, go: `Multiagent`) 구성에서는 에이전트의 고정과 `subagents` (csharp, go: `Subagents`) 또는 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 나열된 모든 에이전트의 고정이 모두 같은 값으로 설정되거나 모두 설정되지 않아야 합니다. [멀티에이전트 오케스트레이션](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration)을 참조하세요. 나중에 고정을 변경하거나 해제하려면 에이전트의 `model` (csharp, go: `Model`) 객체를 업데이트하세요. [업데이트 의미 체계](https://platform.claude.com/docs/ko/managed-agents/agent-setup#update-semantics)에 설명된 대로, `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 없이 `model` (csharp, go: `Model`)을 제공하면 고정이 해제됩니다. ## 에이전트 업데이트하기 에이전트를 업데이트하면 구성이 변경될 때 새 버전이 생성됩니다. `version` (csharp, go: `Version`) 필드는 선택 사항입니다. "optimistic concurrency"(낙관적 동시성 제어)를 위해 제공하거나(불일치 시 409 반환), 생략하여 업데이트를 무조건 적용할 수 있습니다(마지막 쓰기 우선). 보관된 에이전트에 대한 업데이트는 거부됩니다. CLI를 사용하는 경우 에이전트 파일을 편집하고 `ant apply`를 다시 실행하세요. apply가 `version`을 자동으로 제공합니다. ```bash cURL 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 '{ "version": '"$AGENT_VERSION"', "system": "You are a helpful coding agent. Always write tests." }' ``` ```bash CLI ant apply coding-assistant.md ``` ```markdown --- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 --- You are a helpful coding agent. Always write tests. ``` ```python Python updated_agent = client.beta.agents.update( agent.id, version=agent.version, system="You are a helpful coding agent. Always write tests.", ) print(f"New version: {updated_agent.version}") ``` ```typescript TypeScript const updatedAgent = await client.beta.agents.update(agent.id, { version: agent.version, system: "You are a helpful coding agent. Always write tests.", }); console.log(`New version: ${updatedAgent.version}`); ``` ```csharp C# var updatedAgent = await client.Beta.Agents.Update(agent.ID, new() { Version = agent.Version, System = "You are a helpful coding agent. Always write tests.", }); Console.WriteLine($"New version: {updatedAgent.Version}"); ``` ```go Go updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Version: anthropic.Int(agent.Version), System: anthropic.String("You are a helpful coding agent. Always write tests."), }) if err != nil { panic(err) } fmt.Printf("New version: %d\n", updatedAgent.Version) ``` ```java Java var updatedAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .version(agent.version()) .system("You are a helpful coding agent. Always write tests.") .build() ); IO.println("New version: " + updatedAgent.version()); ``` ```php PHP $updatedAgent = $client->beta->agents->update( $agent->id, version: $agent->version, system: 'You are a helpful coding agent. Always write tests.', ); echo "New version: {$updatedAgent->version}\n"; ``` ```ruby Ruby updated_agent = client.beta.agents.update( agent.id, version: agent.version, system_: "You are a helpful coding agent. Always write tests." ) puts "New version: #{updated_agent.version}" ``` 앞의 예제는 생성 응답의 `version`을 제공하므로, 에이전트를 읽은 이후 다른 무언가가 에이전트를 변경하지 않은 경우에만 업데이트가 적용됩니다. 업데이트를 무조건 적용하려면 요청에서 `version`을 생략하세요: ```bash cURL 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." }' ``` ```bash CLI ant beta:agents update \ --agent-id "$AGENT_ID" \ --description "Writes and reviews code." ``` ```python Python unconditional_agent = client.beta.agents.update( agent.id, description="Writes and reviews code.", ) print(f"New version: {unconditional_agent.version}") ``` ```typescript TypeScript const unconditionalAgent = await client.beta.agents.update(agent.id, { description: "Writes and reviews code.", }); console.log(`New version: ${unconditionalAgent.version}`); ``` ```csharp C# var unconditionalAgent = await client.Beta.Agents.Update(agent.ID, new() { Description = "Writes and reviews code.", }); Console.WriteLine($"New version: {unconditionalAgent.Version}"); ``` ```go Go unconditionalAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Description: anthropic.String("Writes and reviews code."), }) if err != nil { panic(err) } fmt.Printf("New version: %d\n", unconditionalAgent.Version) ``` ```java Java var unconditionalAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .description("Writes and reviews code.") .build() ); IO.println("New version: " + unconditionalAgent.version()); ``` ```php PHP $unconditionalAgent = $client->beta->agents->update( $agent->id, description: 'Writes and reviews code.', ); echo "New version: {$unconditionalAgent->version}\n"; ``` ```ruby Ruby unconditional_agent = client.beta.agents.update( agent.id, description: "Writes and reviews code." ) puts "New version: #{unconditional_agent.version}" ``` ### 업데이트 의미 체계 * **`version` (csharp, go: `Version`)**은 선택 사항이며 제공하는 경우 1 이상이어야 합니다. 제공된 경우, 에이전트의 현재 버전과 일치하지 않으면 전송한 필드가 이미 저장된 값과 일치하더라도 요청은 409를 반환합니다. 에이전트를 다시 읽고 재시도하세요. 생략하면 업데이트가 무조건 적용되며, 가장 최근의 업데이트가 동시에 발생한 다른 업데이트를 조용히 대체하고 어느 호출자에게도 오류가 발생하지 않습니다. 대화형 호출자에게는 `version` (csharp, go: `Version`)을 제공하는 것이 권장 기본값이며, 체크인된 에이전트 정의를 동기화하는 CI 작업처럼 루프가 에이전트를 소유하는 선언적 apply 루프에는 생략하는 방식이 적합합니다. * **생략된 필드는 보존됩니다.** 변경하려는 필드만 포함하면 됩니다. * **스칼라 필드**(`model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `name` (csharp, go: `Name`), `description` (csharp, go: `Description`))는 새 값으로 대체됩니다. `system` (csharp, go: `System`; ruby: `system_`)과 `description` (csharp, go: `Description`)은 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`)을 전달하여 지울 수 있습니다. `model` (csharp, go: `Model`)과 `name` (csharp, go: `Name`)은 필수이며 지울 수 없습니다. 제공하는 `model` (csharp, go: `Model`) 객체 내에서 `effort` (csharp, go: `Effort`)는 유일한 예외입니다. 모델 `id` (csharp, go: `ID`)가 변경되지 않은 경우 `effort` (csharp, go: `Effort`)를 생략하면 저장된 effort 수준이 그대로 유지됩니다. 모델 `id` (csharp, go: `ID`)를 변경하면 생략된 `effort` (csharp, go: `Effort`)는 새 모델의 기본값으로 재설정됩니다. 다른 `model` (csharp, go: `Model`) 필드는 객체와 함께 대체됩니다. `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 없이 `model` (csharp, go: `Model`)을 제공하면 에이전트의 추론 지역 고정이 해제됩니다. * **배열 필드**(`tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`))는 새 배열로 완전히 대체됩니다. 배열 필드를 완전히 지우려면 `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) 또는 빈 배열을 전달하세요. * **`multiagent` (csharp, go: `Multiagent`)**는 업데이트가 `multiagent_20261001` 유형을 유지하는 경우 저장된 블록에 수준별로 병합됩니다. 생략한 설정은 저장된 값을 유지하며, 전송한 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록은 저장된 목록을 대체합니다. `multiagent` (csharp, go: `Multiagent`)를 전송하는 그 밖의 업데이트는 저장된 블록 전체를 대체하며, 생략된 설정은 기본값을 갖습니다. 블록 전체를 지우려면 `"multiagent": null` (python: `multiagent=None`; typescript: `multiagent: null`; ruby: `multiagent: nil`; go: `Multiagent: param.NullStruct[anthropic.BetaManagedAgentsMultiagentParamsUnion]()`; java: `.multiagent(Optional.empty())`; csharp: `Multiagent = null`; php: `requestOptions: ['extraBodyParams' => ['multiagent' => null]]`)을 전달하세요. 블록 내부에서 `null`은 설정을 기본값으로 재설정하므로, `workflows` (csharp, go: `Workflows`)를 `null`로 설정하면 동적 워크플로가 켜집니다. [동적 워크플로 켜기](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows)를 참조하세요. * **메타데이터**는 키 수준에서 병합됩니다. 제공한 키는 추가되거나 업데이트됩니다. 생략한 키는 보존됩니다. 특정 키를 삭제하려면 해당 값을 `null`로 설정하세요. * **변경 없음 감지.** 업데이트가 현재 버전과 비교하여 아무런 변경도 만들지 않으면 새 버전이 생성되지 않고 기존 버전이 반환됩니다. * **다른 에이전트의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록은 업데이트되지 않습니다.** `subagents` (csharp, go: `Subagents`) 또는 `workflows` (csharp, go: `Workflows`)의 `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) 목록에 이 에이전트를 나열한 에이전트는, 참조에서 `version` (csharp, go: `Version`)을 생략하더라도 생성 시점 또는 업데이트가 마지막으로 해당 목록을 전송한 시점에 고정된 버전을 유지합니다. 새 버전에 위임하려면 목록이 새 버전을 참조하도록 [해당 에이전트를 나열한 에이전트를 업데이트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#list-the-subagents)하세요. 다음 업데이트는 설명을 지우고, `metadata` (csharp, go: `Metadata`)에서 `team` 키를 삭제하며, `workflows` (csharp, go: `Workflows`)를 `null`로 설정하여 동적 워크플로를 켭니다: ```bash cURL 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": null, "metadata": {"team": null}, "multiagent": {"type": "multiagent_20261001", "workflows": null} }' ``` ```bash CLI ant apply code-reviewer.md ``` ```markdown --- 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. ``` 파일에 더 이상 `description`이나 `team` 키가 없으므로 `ant apply`는 이들에 대해 `null`을 전송합니다. `multiagent` 내부의 설정을 삭제하면 저장된 값이 유지되므로, 파일은 `workflows`를 `null`로 설정합니다. ```python Python cleared_agent = client.beta.agents.update( agent.id, description=None, metadata={"team": None}, multiagent={"type": "multiagent_20261001", "workflows": None}, ) print(f"Description: {cleared_agent.description}") ``` ```typescript TypeScript const clearedAgent = await client.beta.agents.update(agent.id, { description: null, metadata: { team: null }, multiagent: { type: "multiagent_20261001", workflows: null }, }); console.log(`Description: ${clearedAgent.description}`); ``` ```csharp C# var clearedAgent = await client.Beta.Agents.Update(agent.ID, new() { Description = null, Metadata = new Dictionary { ["team"] = null }, Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null }, }); Console.WriteLine($"Description: {clearedAgent.Description}"); ``` ```go Go // Metadata는 map[string]string이므로 team에 대한 null은 요청 옵션으로 전송합니다. clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ Description: param.Null[string](), Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{ OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{ Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](), }, }, }, option.WithJSONSet("metadata.team", nil)) if err != nil { panic(err) } fmt.Printf("Description: %q\n", clearedAgent.Description) ``` ```java Java var clearedAgent = client.beta().agents().update( agent.id(), AgentUpdateParams.builder() .description(Optional.empty()) .metadata( AgentUpdateParams.Metadata.builder() .putAdditionalProperty("team", JsonValue.from(null)) .build() ) .multiagent( BetaManagedAgentsMultiagent20261001Params.builder() .workflows(Optional.empty()) .build() ) .build() ); IO.println("Description: " + clearedAgent.description().orElse(null)); ``` ```php PHP // update()는 null 인수를 제거하므로 null 값은 extraBodyParams로 전달하세요. $clearedAgent = $client->beta->agents->update( $agent->id, requestOptions: [ 'extraBodyParams' => [ 'description' => null, 'metadata' => ['team' => null], 'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null], ], ], ); echo 'Description: ' . json_encode($clearedAgent->description) . "\n"; ``` ```ruby Ruby cleared_agent = client.beta.agents.update( agent.id, description: nil, metadata: {team: nil}, multiagent: {type: :multiagent_20261001, workflows: nil} ) puts "Description: #{cleared_agent.description.inspect}" ``` ## 에이전트 수명 주기 | 작업 | 동작 | | ------------ | ------------------------------------------------------- | | **업데이트** | 구성이 변경될 때 새 에이전트 버전을 생성합니다. | | **버전 목록 조회** | 시간 경과에 따른 변경 사항을 추적할 수 있도록 전체 버전 기록을 반환합니다. | | **보관** | 에이전트를 읽기 전용으로 만듭니다. 새 세션은 이를 참조할 수 없지만 기존 세션은 계속 실행됩니다. | ### 버전 목록 조회 전체 버전 기록을 가져와 에이전트가 시간에 따라 어떻게 변경되었는지 추적하세요. 결과는 페이지로 나뉘며, SDK 예제는 모든 페이지를 자동으로 가져옵니다. ```bash cURL 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" ``` ```bash CLI ant beta:agents:versions list --agent-id "$AGENT_ID" ``` ```python Python for version in client.beta.agents.versions.list(agent.id): print(f"Version {version.version}: {version.updated_at.isoformat()}") ``` ```typescript TypeScript for await (const version of client.beta.agents.versions.list(agent.id)) { console.log(`Version ${version.version}: ${version.updated_at}`); } ``` ```csharp C# var versions = await client.Beta.Agents.Versions.List(agent.ID); await foreach (var version in versions.Paginate()) { Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}"); } ``` ```go Go iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{}) for iter.Next() { version := iter.Current() fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339)) } if err := iter.Err(); err != nil { panic(err) } ``` ```java Java for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) { IO.println("Version " + version.version() + ": " + version.updatedAt()); } ``` ```php PHP foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) { echo "Version {$version->version}: {$version->updatedAt->format(\DateTimeInterface::ATOM)}\n"; } ``` ```ruby Ruby client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version| puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}" end ``` ### 에이전트 보관하기 보관하면 에이전트가 읽기 전용이 되며 되돌릴 수 없습니다. 기존 세션은 계속 실행되지만 새 세션은 해당 에이전트를 참조할 수 없습니다. 응답은 `archived_at` (java, php: `archivedAt`; csharp, go: `ArchivedAt`)을 보관 타임스탬프로 설정합니다. ```bash cURL 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" ``` ```bash CLI ant beta:agents archive --agent-id "$AGENT_ID" ``` ```python Python archived = client.beta.agents.archive(agent.id) print(f"Archived at: {archived.archived_at.isoformat()}") ``` ```typescript TypeScript const archived = await client.beta.agents.archive(agent.id); console.log(`Archived at: ${archived.archived_at}`); ``` ```csharp C# var archived = await client.Beta.Agents.Archive(agent.ID); Console.WriteLine($"Archived at: {archived.ArchivedAt:O}"); ``` ```go Go archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{}) if err != nil { panic(err) } fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339)) ``` ```java Java var archived = client.beta().agents().archive(agent.id()); IO.println("Archived at: " + archived.archivedAt().orElseThrow()); ``` ```php PHP $archived = $client->beta->agents->archive($agent->id); echo "Archived at: {$archived->archivedAt->format(\DateTimeInterface::ATOM)}\n"; ``` ```ruby Ruby archived = client.beta.agents.archive(agent.id) puts "Archived at: #{archived.archived_at.iso8601}" ``` ## 다음 단계 에이전트가 사용할 수 있는 도구를 구성합니다. 도메인별 워크플로를 위해 재사용 가능한 파일 시스템 기반 전문 지식을 에이전트에 연결합니다. 에이전트를 실행하고 작업 수행을 시작할 세션을 생성합니다. Claude Managed Agents의 이벤트 유형, 자체 호스팅 워커 CLI 플래그, 지원되는 MCP 서버 유형, 속도 제한 및 브랜딩 가이드라인입니다.