Определите своего агента

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

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

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

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

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

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

В примерах используются curl, CLI ant или один из SDK. Если вы ещё ничего из этого не настроили, быстрый старт описывает установку и настройку клиента.

agent=$(ant beta:agents create --format json < coding-assistant.agent.yaml)

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

name: Coding Assistant
model:
  id: claude-opus-5
system: You are a helpful coding agent.
tools:
  - type: agent_toolset_20260401

Ответ повторяет вашу конфигурацию и добавляет поля 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",
    "effort": { "type": "high" },
    "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 ответа:

agent=$(ant beta:agents create --format json < geo-pinned.agent.yaml)

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

name: Geo-pinned assistant
model:
  id: claude-opus-5
  inference_geo: us
system: You are a helpful assistant.

Закрепление inference_geo проверяется на соответствие allowed_inference_geos рабочего пространства при сохранении агента, при создании сессии на его основе и на каждом ходе, который обслуживает сессия. Если список разрешённых значений рабочего пространства сужается так, что закрепление больше не разрешено, новые сессии не могут быть созданы на основе агента, а работающие сессии отклоняют дальнейшие ходы; для закреплений никогда не делается исключений, поскольку рабочие пространства полагаются на них для соблюдения нормативных требований и резидентности данных.

Установка inference_geo для модели, которая не поддерживает географическое закрепление инференса, возвращает ошибку 400; список моделей, которые его поддерживают, см. в разделе Доступность моделей. В конфигурации multiagent закрепление координатора и каждого участника списка должны быть либо все установлены в одно и то же значение, либо все не заданы; см. Мультиагентная оркестрация. Чтобы позже изменить или снять закрепление, обновите объект model агента; передача model без inference_geo снимает его, как описано в разделе Семантика обновления.

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

Обновление агента создаёт новую версию, когда конфигурация изменяется. Поле version необязательно: укажите его для оптимистичного управления параллелизмом (несовпадение возвращает 409) или опустите, чтобы применить обновление безусловно (побеждает последняя запись). Обновления архивированных агентов отклоняются.

ant beta:agents update --agent-id "$AGENT_ID" < coding-assistant.agent.yaml

name: Coding Assistant
model:
  id: claude-opus-5
system: You are a helpful coding agent. Always write tests.
tools:
  - type: agent_toolset_20260401

В предыдущем примере version берётся из ответа на создание, поэтому обновление применяется только в том случае, если ничто другое не изменило агента с момента его чтения. Чтобы применить обновление безусловно, опустите version в запросе:

updated_agent=$(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."
  }')

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

Семантика обновления

• version необязательно и при указании должно быть не меньше 1. Если оно указано, запрос возвращает 409, когда значение не совпадает с текущей версией агента, даже если отправленные вами поля уже совпадают с сохранёнными значениями; перечитайте агента и повторите попытку. Если оно опущено, обновление применяется безусловно, и самое последнее обновление молча заменяет любое параллельное, без ошибки для обоих вызывающих. Указание version — рекомендуемый вариант по умолчанию для интерактивных вызывающих, а его отсутствие подходит для декларативных циклов применения, например задания CI, синхронизирующего зафиксированные в репозитории определения агентов, где цикл владеет агентом.

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

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

• Поля-массивы (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"

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