---
title: "更新智能体（AI 角色）"
method: PUT
path: "/api/v1/ai/agents/{agent_id}"
tags: ["agents", "characters", "android_app", "web_app", "evaluation"]
---

# 更新智能体（AI 角色）

`PUT /api/v1/ai/agents/{agent_id}`

更新任何图片，都会将图片全部记录在 background_images 字段中，用于保存历史记录如果没有提供 avatar，则会自动截取头像，并记录在 avatar 字段中

## Path parameters

- `agent_id` string, required

## Request body

- AgentUpdate — 更新AI角色
  - `name` string, nullable
  - `gender` string, nullable
  - `avatar` string, nullable
  - `background` string, nullable
  - `background_images` string[], nullable
  - `background_animated` string, nullable
  - `voice_id` string, nullable
  - `settings` object, nullable
  - `intro` string, nullable
  - `opening` string, nullable
  - `opening_audio_url` string, nullable
  - `visibility` 'PUBLIC' | 'PRIVATE' — AI 角色可见性
  - `source` 'USER_CREATED' | 'AUTO_GENERATED' — AI 角色来源
  - `photos` string[], nullable
  - `category` string, nullable
  - `prompt` string, nullable — 已废弃 - 请使用personality字段代替
  - `main_prompt` string, nullable
  - `mode_prompt` string, nullable
  - `character_card_spec` string, nullable
  - `personality` string, nullable
  - `scenario` string, nullable
  - `message_example` string, nullable
  - `creator_notes` string, nullable
  - `post_history_instructions` string, nullable
  - `alternate_greetings` string[], nullable
  - `character_book` object, nullable
  - `tags` string[], nullable
  - `character_version` string, nullable
  - `extensions` object, nullable
  - `llm_config` ModelConfig — AI模型配置
    - `model` string, nullable
    - `api_key` string, nullable
    - `base_url` string, nullable
    - `temperature` number, nullable — Temperature for response generation
    - `max_tokens` integer, nullable — Maximum tokens in response
    - `top_p` number, nullable — Top-p sampling parameter
    - `top_k` integer, nullable — Top-k sampling parameter
    - `frequency_penalty` number, nullable — Frequency penalty
    - `presence_penalty` number, nullable — Presence penalty
  - `meta_data` AgentMetaData — Agent 元数据模型
    - `score` integer, nullable — Agent 评分
    - `comment` string, nullable — Agent 备注信息
  - `energy_points` integer, nullable — 需要新增的能量点数，会累加到 agent 的积分列中
  - `replace_background_images` boolean, nullable — 是否替换 background_images 列表。为 True 时完全替换，为 False 或 None 时追加
  - `request_id` string, nullable

## Response `200`

Successful Response

- Agent — AI角色，在 sqlalchemy 模型基础上添加额外多表查询来的数据
  - `name` string, required
  - `gender` string, required
  - `avatar` string, nullable
  - `background` string, nullable
  - `background_images` string[], nullable
  - `background_animated` string, nullable
  - `voice_id` string, nullable
  - `settings` object, nullable
  - `intro` string, nullable
  - `opening` string, nullable
  - `opening_audio_url` string, nullable
  - `visibility` 'PUBLIC' | 'PRIVATE' — AI 角色可见性
  - `source` 'USER_CREATED' | 'AUTO_GENERATED' — AI 角色来源
  - `photos` string[], nullable
  - `category` string, nullable
  - `prompt` string, nullable — 已废弃 - 请使用personality字段代替
  - `main_prompt` string, nullable — 主提示词 - 作为第一个system message，覆盖全局默认主提示词。可以是预设 ID 或自定义文本
  - `mode_prompt` string, nullable — 模式提示词 - 放在角色卡提示词后面，覆盖全局默认模式提示词。可以是预设 ID 或自定义文本
  - `character_card_spec` string, nullable
  - `personality` string, nullable — 角色性格特点 (推荐)
  - `scenario` string, nullable — 背景设定 (推荐)
  - `message_example` string, nullable — 对话示例
  - `creator_notes` string, nullable — 创作者备注
  - `post_history_instructions` string, nullable
  - `alternate_greetings` string[], nullable
  - `character_book` object, nullable
  - `tags` string[], nullable
  - `character_version` string, nullable
  - `extensions` object, nullable
  - `llm_config` ModelConfig — AI模型配置
    - `model` string, nullable
    - `api_key` string, nullable
    - `base_url` string, nullable
    - `temperature` number, nullable — Temperature for response generation
    - `max_tokens` integer, nullable — Maximum tokens in response
    - `top_p` number, nullable — Top-p sampling parameter
    - `top_k` integer, nullable — Top-k sampling parameter
    - `frequency_penalty` number, nullable — Frequency penalty
    - `presence_penalty` number, nullable — Presence penalty
  - `meta_data` AgentMetaData — Agent 元数据模型
    - `score` integer, nullable — Agent 评分
    - `comment` string, nullable — Agent 备注信息
  - `id` string, required
  - `readable_id` string, required
  - `status` 'PENDING' | 'APPROVED' | 'REJECTED', required — AI角色状态
  - `creator_id` string, nullable
  - `created_at` integer, required
  - `updated_at` integer, nullable
  - `deleted_at` integer, nullable
  - `version` integer, required
  - `energy_points` integer — Agent 当前能量点数，对应数据库 points 列
  - `is_followed` boolean
  - `follower_count` integer
  - `connector_count` integer
  - `creator` User — 返回给客户端的用户信息
    - `readable_id` string, required
    - `nickname` string, nullable
    - `avatar` string, nullable
    - `email` string, nullable
    - `user_photo` string, nullable
    - `phone` string, nullable
    - `gender` 'MALE' | 'FEMALE' | 'OTHER' — 性别
    - `age_group` string, nullable
    - `description` string, nullable
    - `system_language` string, nullable
    - `id` string, required
    - `auth_type` string, required
    - `is_active` boolean, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, nullable
    - `is_superuser` boolean
    - `public_agents_count` integer, nullable
    - `total_public_agents_follows` integer, nullable
    - `followers_count` integer, nullable
    - `connector_count` integer, nullable
    - `actions` UserAction[]
      - `type` 'request_feedback', required — 用户行动类型枚举
      - `enabled` boolean, required
  - `avatar_size` ImageSize — Image size
    - `width` integer, required
    - `height` integer, required
  - `background_size` ImageSize — Image size
    - `width` integer, required
    - `height` integer, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-28** `1e014c365df2` — 1 warning, 2 info
  - removed the optional property `user` from the response with the `200` status
  - added the new optional request property `source`
  - added the optional property `source` to the response with the `200` status
- **2026-01-12** `5b77ae7cc5c4` — 2 info
  - added the new optional request property `replace_background_images`
  - added the optional property `creator/anyOf[subschema #1: User]/user_photo` to the response with the `200` status
- **2025-12-12** `b2372bf7485c` — 3 info
  - added the new optional request property `energy_points`
  - added the optional property `creator/anyOf[subschema #1: User]/actions` to the response with the `200` status
  - added the optional property `energy_points` to the response with the `200` status
- **2025-11-25** `05cf5f034c74` — 6 info
  - api tag `android_app` added
  - api tag `evaluation` added
  - api tag `web_app` added
  - added the new optional request property `background_animated`
  - …2 more
- **2025-09-29** `bd9470194fe1` — 2 info
  - added the new optional request property `request_id`
  - added the optional property `user` to the response with the `200` status

[Full history](https://skmtc.dev/nascentcore/apis/inty-backend/changes/api/v1/ai/agents/:agent_id/put.md)

---

[API](https://skmtc.dev/nascentcore/apis/inty-backend.md) · [All operations](https://skmtc.dev/nascentcore/apis/inty-backend/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nascentcore/inty-backend/revisions/1e014c365df2/schema)