Create an agent profile

POST 
/api/v1/agent-profiles/create

Creates a profile in the caller's project library. A duplicate profile ID fails with ALREADY_EXISTS; use update to replace an existing profile. The store assigns the initial immutable version. The system prompt must be a valid template and every variable spec needs a unique name; otherwise create fails with 400.

Enabled profiles are immediately selectable. Disabled profiles are omitted from the selection library, and a direct send naming one fails with ACTIVE_PROFILE_DISABLED. Queued messages currently take a different fallback path; see unusable profiles.

Use this in a guide: Build a reusable assistant profile · Keep a model on the providers you choose

Request

Responses

200

Profile created; the stored record is echoed back

Create a reusable support profile; choose a new profileId in your project.

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

Request example

{
  "profile": {
    "profileId": "support-assistant",
    "name": "Support assistant",
    "whenToUse": "Help users answer product questions.",
    "generationConfig": {
      "systemPrompt": "Answer clearly using the supplied product information."
    }
  }
}

Guide request for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values.

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

Request example

{
  "profile": {
    "profileId": "nutrition_coach",
    "name": "Nutrition Coach",
    "description": "Food, meals and macros.",
    "whenToUse": "Use when the user asks about food, meals, or macros.",
    "keywords": [
      "nutrition",
      "food",
      "macros"
    ],
    "enabled": true,
    "generationConfig": {
      "model": "YOUR_MODEL_ID",
      "systemPrompt": "You are a nutrition coach. Be concise and practical.",
      "temperature": 0.4
    }
  }
}

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

Section ID: DOC-MA-profiles-prompts-api-createAgentProfile#example-agent-profiles-createAgentProfile-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
  }
}

Illustrative response for Step 1: Save the assistant instructions. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-profiles-prompts-api-createAgentProfile#example-cookbook-managed-agents-profiles-prompts-index-json-01-response

Response example

{
  "profile": {
    "profileId": "nutrition_coach",
    "name": "Nutrition Coach",
    "description": "Food, meals and macros.",
    "whenToUse": "Use when the user asks about food, meals, or macros.",
    "keywords": [
      "nutrition",
      "food",
      "macros"
    ],
    "enabled": true,
    "generationConfig": {
      "model": "YOUR_MODEL_ID",
      "systemPrompt": "You are a nutrition coach. Be concise and practical.",
      "temperature": 0.4
    },
    "version": 1
  }
}

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

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