Section ID:
DOC-API-MODEL-schema-1hmbcecg1j#overview
AgentProfile
A reusable persona with model configuration, tools and metadata describing when it should be selected. See the profile-selection and versioning guide for profile resolution and fragment versions.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-profileidprofileId | string | Optional | Stable id, unique within the project library. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-descriptiondescription | string | Optional | Human-facing summary. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-whentousewhenToUse | string | Optional | Routing hint, Skill-style "use when…" |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-keywordskeywords | Array of string | Optional | Keywords associated with discovery or selection of the agent profile. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-enabledenabled | 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. Disabled profiles are not selectable. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-generationconfiggenerationConfig | GenerationConfig | Optional | Model, sampling, and tool configuration used for generation. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-mcpserversmcpServers | Array of MCPServerReference | Optional | MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-variablespecsvariableSpecs | Array of PromptVariableSpec | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt_variables. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#request-field-versionversion | string (int64) | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$. |
name
Display name used when selecting an agent profile.
e.g. "Nutrition Coach"
In responses
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-profileidSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-profileidprofileId | string | Optional | Stable id, unique within the project library. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-nameSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-namename | string | Optional | See meaning below. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-descriptionSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-descriptiondescription | string | Optional | Human-facing summary. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-whentouseSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-whentousewhenToUse | string | Optional | Routing hint, Skill-style "use when…" |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-keywordsSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-keywordskeywords | Array of string | Optional | Keywords associated with discovery or selection of the agent profile. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-enabledSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-enabledenabled | 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. Disabled profiles are not selectable. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-generationconfigSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-generationconfiggenerationConfig | GenerationConfig | Optional | Model, sampling, and tool configuration used for generation. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-mcpserversSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-mcpserversmcpServers | Array of MCPServerReference | Optional | MCP servers used for tool discovery when this profile is active. This list replaces the conversation-wide MCP server list for those turns. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-variablespecsSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-variablespecsvariableSpecs | Array of PromptVariableSpec | Optional | Variables consumed by the profile’s system-prompt template, rendered from the conversation’s prompt_variables. |
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#field-versionSection ID: DOC-API-MODEL-schema-1hmbcecg1j#response-field-versionversion | string (int64) | Optional | Output-only immutable revision of the profile. Versions start at one and increase on successful mutations; values supplied on writes are ignored. Pattern: ^-?\d+$. |
name
Display name used when selecting an agent profile.
e.g. "Nutrition Coach"
Where used
Section ID: DOC-API-MODEL-schema-1hmbcecg1j#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| 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 |
| Update an agent profile | POST /api/v1/agent-profiles/update |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1hmbcecg1j