에이전트 정의하기

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

<MultiFileExample language="cli" label="CLI">
  ```bash CLI
  ant apply coding-assistant.md
  ```

  <File filename="coding-assistant.md">
    ```markdown
    ---
    name: Coding Assistant
    model: claude-opus-5-5
    tools:
      - type: agent_toolset_20260401
    ---

    You are a helpful coding agent.
    ```
  </File>
</MultiFileExample>

```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"},
    ],
)

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" }],
});

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",
        },
    ],
});

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)
}

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()
);

$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',
        ),
    ],
);

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"}]
)

echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"

<MultiFileExample language="cli" label="CLI">
  ```bash CLI
  ant apply geo-pinned-assistant.md
  ```

  <File filename="geo-pinned-assistant.md">
    ```markdown
    ---
    name: Geo-pinned assistant
    model:
      id: claude-opus-5-5
      inference_geo: us
    ---

    You are a helpful assistant.
    ```
  </File>
</MultiFileExample>

```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}")

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}`);

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}");

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)

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());

$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";

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}"

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

</CodeGroup>

### Update semantics

* **`version`** is optional and must be at least 1 when supplied. When supplied, the request returns a 409 if it doesn't match the agent's current version, even when the fields you send already match the stored values; re-read the agent and retry. When omitted, the update applies unconditionally and the most recent update silently replaces any concurrent one, with no error to either caller. Supplying `version` is the recommended default for interactive callers, and omitting it fits declarative apply loops, such as a CI job that syncs checked-in agent definitions, where the loop owns the agent.

* **Omitted fields are preserved.** You only need to include the fields you want to change.

* **Scalar fields** (`model`, `system`, `name`, `description`) are replaced with the new value. `system` and `description` can be cleared by passing `null`. `model` and `name` are mandatory and cannot be cleared. Within a `model` object you supply, `effort` is the sole exception: if the model `id` is unchanged, omitting `effort` leaves the stored effort level unchanged. If you change the model `id`, an omitted `effort` resets to the new model's default. Other `model` fields are replaced along with the object: supplying `model` without `inference_geo` clears the agent's inference geo pin.

* **Array fields** (`tools`, `mcp_servers`, `skills`) are fully replaced by the new array. To clear an array field entirely, pass `null` or an empty array.

* **`multiagent`** is replaced as a whole, including its `agents` roster. Pass `null` to clear it.

* **Metadata** is merged at the key level. Keys you provide are added or updated. Keys you omit are preserved. To delete a specific key, set its value to `null`.

* **No-op detection.** If the update produces no change relative to the current version, no new version is created and the existing version is returned.

* **Coordinator rosters are not updated.** Coordinators that reference this agent in their `multiagent.agents` roster keep the version that was pinned when the coordinator was created or last updated, even if the reference omits `version`. To delegate to the new version, [update the coordinator](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#configure-the-coordinator) so its roster references it.

## Agent lifecycle

| Operation         | Behavior                                                                                            |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| **Update**        | Generates a new agent version when the configuration changes.                                       |
| **List versions** | Returns the full version history so you can track changes over time.                                |
| **Archive**       | Makes the agent read-only. New sessions cannot reference it, but existing sessions continue to run. |

### List versions

에이전트가 시간에 따라 어떻게 변했는지 추적하기 위해 전체 버전 기록을 가져와요. 결과는 페이지로 나뉘며, SDK 예시는 자동으로 모든 페이지를 가져와요.

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

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

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

for await (const version of client.beta.agents.versions.list(agent.id)) {
  console.log(`Version ${version.version}: ${version.updated_at}`);
}

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}");
}

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)
}

for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
    IO.println("Version " + version.version() + ": " + version.updatedAt());
}

foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
    echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n";
}

client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
  puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
end

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

```bash CLI
ant beta:agents archive --agent-id "$AGENT_ID"

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

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

const archived = await client.beta.agents.archive(agent.id);
console.log(`Archived at: ${archived.archived_at}`);

var archived = await client.Beta.Agents.Archive(agent.ID);
Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");

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))

var archived = client.beta().agents().archive(agent.id());
IO.println("Archived at: " + archived.archivedAt().orElseThrow());

$archived = $client->beta->agents->archive($agent->id);

echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n";

archived = client.beta.agents.archive(agent.id)
puts "Archived at: #{archived.archived_at.iso8601}"