AgentProfile
A reusable persona with model configuration, tools and metadata describing when it should be selected.
See Profile selection and versioning for profile resolution and fragment versions.
Usage profiles
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
profileId | string | Optional | Stable id, unique within the project library. |
name | string | Optional | Display name used when selecting an agent profile. |
description | string | Optional | Human-facing summary. |
whenToUse | string | Optional | Routing hint, Skill-style "use when…" |
keywords | Array of string | Optional | Keywords associated with discovery or selection of the agent profile. |
enabled | boolean | Optional; explicit presence | Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. |
generationConfig | GenerationConfig | Optional | --- the bundle (reused as-is: model, system_prompt, temperature, …) --- Model, sampling, and tool configuration used for generation. |
mcpServers | Array of MCPServerReference | Optional | --- the tool bundle for this profile --- Drives per-profile MCP tool discovery; replaces the conversation-wide ConversationSettings.mcp_servers for turns where this profile is active. |
variableSpecs | Array of PromptVariableSpec | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt_variables. |
version | integer (int32) | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Minimum: -2147483648. Maximum: 2147483647. |
disableDefaultTools | boolean | Optional | Exclude the default MCP tool catalog from this profile’s effective server set. When true, only the profile’s configured MCP servers are used. |
In responses
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
profileId | string | Optional | Stable id, unique within the project library. |
name | string | Optional | Display name used when selecting an agent profile. |
description | string | Optional | Human-facing summary. |
whenToUse | string | Optional | Routing hint, Skill-style "use when…" |
keywords | Array of string | Optional | Keywords associated with discovery or selection of the agent profile. |
enabled | boolean | Optional; explicit presence | Whether the profile is enabled for selection. Omission during creation defaults to true; an explicitly false value creates a disabled profile. |
generationConfig | GenerationConfig | Optional | --- the bundle (reused as-is: model, system_prompt, temperature, …) --- Model, sampling, and tool configuration used for generation. |
mcpServers | Array of MCPServerReference | Optional | --- the tool bundle for this profile --- Drives per-profile MCP tool discovery; replaces the conversation-wide ConversationSettings.mcp_servers for turns where this profile is active. |
variableSpecs | Array of PromptVariableSpec | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt_variables. |
version | integer (int32) | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Minimum: -2147483648. Maximum: 2147483647. |
disableDefaultTools | boolean | Optional | Exclude the default MCP tool catalog from this profile’s effective server set. When true, only the profile’s configured MCP servers are used. |
Where used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
Download the public reference contract.
Document: DOC-API-MODEL-agent-profile.