Import a prompt library

POST /api/v1/agent-profiles/import

Bulk-converts a source prompt library into profiles and reusable fragments. Conversion happens at import time: prompts are rewritten to the platform template syntax and variable specifications are derived from usage. The platform never interprets the source DSL when serving a turn.

Existing rows cause the import to stop at the first conflict with ALREADY_EXISTS, unless overwrite is enabled. In overwrite mode, existing profiles and fragments are replaced. Writes apply fragments before profiles and are not atomic across rows: a later failure can leave earlier writes in place. Re-read the library and reconcile it before retrying.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Build a reusable assistant profile

Request

Responses

Converted profiles and fragments, as stored

Import one source template as a new profile; use overwrite only when replacement is intended.

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

Request example

{
  "templates": [
    {
      "profileId": "support-assistant",
      "name": "Support assistant",
      "whenToUse": "Help users answer product questions.",
      "sourceDsl": "Answer clearly using the supplied product information."
    }
  ]
}

Guide request for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.

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

Request example

{
  "templates": [
    {
      "profileId": "nutrition_coach",
      "name": "Nutrition Coach",
      "whenToUse": "Use when the user asks about food, meals, or macros.",
      "keywords": [
        "nutrition"
      ],
      "sourceDsl": "@include _shared/safety.txt\n\nYou are a nutrition coach for {{user_name}}.",
      "generationConfig": {
        "model": "YOUR_MODEL_ID"
      }
    }
  ],
  "fragments": [
    {
      "fragmentId": "safety",
      "name": "Safety rules",
      "path": "_shared/safety.txt",
      "sourceDsl": "Never give medical advice."
    }
  ],
  "emitFragments": true
}

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

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

Response example

{
  "profiles": [
    {
      "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
    }
  ],
  "fragments": [
    {
      "fragmentId": "example_123",
      "name": "example",
      "content": "Example text"
    }
  ]
}

Illustrative response for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.

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

Response example

{
  "profiles": [
    {
      "profileId": "nutrition_coach",
      "version": 1
    }
  ],
  "fragments": [
    {
      "fragmentId": "safety",
      "name": "Safety rules"
    }
  ]
}

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

Section	Stable reference
Import a prompt library	`DOC-MA-profiles-prompts-api-importAgentProfiles#overview`
Request	`DOC-MA-profiles-prompts-api-importAgentProfiles#request`
Responses	`DOC-MA-profiles-prompts-api-importAgentProfiles#responses`

Import a prompt library

/api/v1/agent-profiles/import

Request​

Responses​

Import one source template as a new profile; use overwrite only when replacement is intended.​

Guide request for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.​

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

Illustrative response for Variant: migrate an existing prompt library. Replace example resource identifiers with your own authorized values.​