Update an agent profile

POST 
/api/v1/agent-profiles/update

Updates an agent profile. Each successful update appends a new immutable version; the profile ID remains fixed and the store assigns the version.

Which fields change

Without an updateMask, only the fields the supplied profile sets change, and inside generationConfig only the sub-fields it sets. Nothing left out is cleared, so clearing a field needs a mask. A mask naming fields changes exactly those, clearing a named field the profile leaves unset; to replace the whole profile, name every field. An update that would leave name or whenToUse empty is refused with 400, as is one writing a system prompt that is not a valid template or variable specs without unique names.

Use this in a guide: Build a reusable assistant profile · Keep a model on the providers you choose · Reuse and update shared assistant instructions

Request

Responses

200

Profile updated; the new stored record is echoed back

Rename an existing profile without replacing its generation configuration.

Section ID: DOC-MA-profiles-prompts-api-updateAgentProfile#example-agent-profiles-updateAgentProfile-request

Request example

{
  "profileId": "support-assistant",
  "profile": {
    "name": "Customer support assistant"
  },
  "updateMask": "name"
}

Guide request for Recipe: change the response style without replacing the profile. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-profiles-prompts-api-updateAgentProfile#example-cookbook-managed-agents-profiles-prompts-index-03-request

Request example

{
  "profileId": "nutrition_coach",
  "profile": {
    "generationConfig": {
      "temperature": 0.2
    }
  },
  "updateMask": "generationConfig.temperature"
}

Guide request for Retire an assistant without stranding its conversations. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-profiles-prompts-api-updateAgentProfile#example-cookbook-managed-agents-profiles-prompts-index-json-06-request

Request example

{
  "profileId": "nutrition_coach",
  "profile": {
    "enabled": false
  },
  "updateMask": "enabled"
}

Guide request for Step 1: Create the block and include it in the profile. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-profiles-prompts-api-updateAgentProfile#example-cookbook-managed-agents-profiles-prompts-prompt-fragments-json-02-request

Request example

{
  "profileId": "nutrition_coach",
  "profile": {
    "generationConfig": {
      "systemPrompt": "{{template \"safety\" .}}\n\nYou are a nutrition coach for {{.userName}}."
    }
  },
  "updateMask": "generationConfig.systemPrompt"
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.

Section ID: DOC-MA-profiles-prompts-api-updateAgentProfile#example-agent-profiles-updateAgentProfile-response

Response example

{
  "profile": {
    "profileId": "example_123",
    "name": "example",
    "description": "example",
    "whenToUse": "example",
    "keywords": [
      "example_123"
    ],
    "enabled": true,
    "generationConfig": {
      "model": "example",
      "models": [
        "example"
      ],
      "systemPrompt": "Example text",
      "transforms": [
        "example"
      ],
      "temperature": 1,
      "topP": 1,
      "maxOutputTokens": 1,
      "frequencyPenalty": 1,
      "presencePenalty": 1,
      "stopSequences": [
        "example"
      ],
      "seed": "1",
      "allowParallelToolCalls": true,
      "topK": 1,
      "repetitionPenalty": 1,
      "topLogprobs": 1,
      "minP": 1,
      "topA": 1,
      "user": "example",
      "modalities": [
        "MODALITY_TEXT"
      ],
      "languagePreference": "en-US",
      "requestTimeoutSeconds": 1,
      "clearTools": true
    },
    "mcpServers": [
      {
        "serverId": "example_123",
        "enabled": true,
        "priority": 1,
        "allowlistToolPatterns": [
          "example"
        ],
        "blocklistToolPatterns": [
          "example"
        ]
      }
    ],
    "variableSpecs": [
      {
        "name": "example",
        "description": "example",
        "required": true,
        "defaultValue": "example",
        "type": "VAR_TYPE_STRING"
      }
    ],
    "version": 1
  }
}

Document ID: DOC-MA-profiles-prompts-api-updateAgentProfile. Section identities and revisions.

Section	Stable reference
Update an agent profile	DOC-MA-profiles-prompts-api-updateAgentProfile#overview
Request	DOC-MA-profiles-prompts-api-updateAgentProfile#request
Responses	DOC-MA-profiles-prompts-api-updateAgentProfile#responses