Определение агента

Агент — это многократно используемая версионируемая конфигурация, которая определяет персону и возможности. Она объединяет модель, системную подсказку, инструменты, серверы MCP и навыки, которые определяют поведение Claude во время сеанса.

Создайте агента один раз как многократно используемый ресурс и ссылайтесь на него по ID каждый раз, когда вы запускаете сеанс. Агенты версионируются, и ими проще управлять во множестве сеансов.

Поля конфигурации агента

Вы также можете переопределить model, system, tools, mcp_servers и skills для отдельного сеанса, не изменяя агента. Переопределение model полностью заменяет объект model агента, поэтому собственное значение effort агента не переносится. Чтобы запустить сеанс с определённым уровнем усилий, задайте effort внутри объекта model переопределения. См. Переопределение конфигурации агента для сеанса.

Создание агента

В следующем примере определяется агент для программирования, который использует новейшую модель Claude Opus и имеет доступ к готовому набору инструментов агента. Этот набор инструментов позволяет агенту писать код, читать файлы, выполнять поиск в интернете и многое другое. Полный список поддерживаемых инструментов см. в справочнике по инструментам агента.

В примерах используется curl, CLI ant или один из 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, а также заполняет опущенные вами поля model, такие как effort, значениями по умолчанию. Значение 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 как объект и задайте inference_geo рядом с id. Поле принимает "us" или "global". Если оно не задано, каждый запрос к модели следует географии инференса по умолчанию для рабочего пространства на момент обслуживания запроса. Элементы управления географией на уровне рабочего пространства и цены см. в разделе Резидентность данных.

В следующем примере агент закрепляется за инференсом в США и выводится значение inference_geo из объекта model агента:

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 закрепление агента и закрепление каждого агента, указанного в списке predefined_agents в subagents или workflows, должны быть либо все установлены в одно и то же значение, либо все не заданы; см. Мультиагентная оркестрация. Чтобы позже изменить или снять закрепление, обновите объект model агента; передача model без inference_geo снимает его, как описано в разделе Семантика обновления.

Обновление агента

Обновление агента создаёт новую версию, если конфигурация изменяется. Поле version необязательно: укажите его для оптимистичного управления параллелизмом (при несовпадении возвращается 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, которое синхронизирует зафиксированные в репозитории определения агентов, когда агентом владеет этот цикл.

• Опущенные поля сохраняются. Нужно включать только те поля, которые вы хотите изменить.

• Скалярные поля (model, system, name, description) заменяются новым значением. system и description можно очистить, передав None. model и name обязательны и не могут быть очищены. Внутри передаваемого вами объекта model единственным исключением является effort: если id модели не изменился, отсутствие effort оставляет сохранённый уровень усилий без изменений. Если вы меняете id модели, опущенное effort сбрасывается к значению по умолчанию для новой модели. Остальные поля model заменяются вместе с объектом: передача model без inference_geo снимает закрепление географии инференса агента.

• Поля-массивы (tools, mcp_servers, skills) полностью заменяются новым массивом. Чтобы полностью очистить поле-массив, передайте None или пустой массив.

• multiagent объединяется с сохранённым блоком уровень за уровнем, если обновление сохраняет тип multiagent_20261001. Опущенная вами настройка сохраняет своё сохранённое значение, а отправленный вами список predefined_agents заменяет сохранённый список. Любое другое обновление, отправляющее multiagent, заменяет сохранённый блок целиком, а опущенные в нём настройки принимают значения по умолчанию. Передайте multiagent=None, чтобы очистить весь блок. Внутри блока null сбрасывает настройку к значению по умолчанию, поэтому установка workflows в null включает динамические рабочие процессы. См. Включение динамических рабочих процессов.

• Метаданные объединяются на уровне ключей. Переданные вами ключи добавляются или обновляются. Опущенные ключи сохраняются. Чтобы удалить определённый ключ, установите его значение в null.

• Обнаружение пустых операций. Если обновление не вносит изменений относительно текущей версии, новая версия не создаётся и возвращается существующая версия.

• Списки predefined_agents других агентов не обновляются. Агенты, которые указывают этого агента в списке predefined_agents в subagents или workflows, сохраняют версию, которая была закреплена при их создании или при последнем обновлении, отправившем этот список, даже если ссылка не содержит version. Чтобы делегировать работу новой версии, обновите агента, который её указывает, чтобы список ссылался на новую версию.

Следующее обновление очищает описание, удаляет ключ team из metadata и устанавливает 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()}")

Следующие шаги