> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Materialize Agent Profile > Preview the launch of a profile; return a diagnostics report. Previews the stored profile ``name``, or ``body.profile`` when given (so an editor can preview before saving), with the same resolve and finalize as a launch, against the runtime this server launches into. Dangling references are reported in the body (valid=False) rather than raising — the only error statuses are 404 (unknown stored profile) and 422 (invalid draft). resolved_settings is redacted (no raw secrets). ## OpenAPI ````yaml /openapi/agent-sdk.json post /api/agent-profiles/{name}/materialize openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/agent-profiles/{name}/materialize: post: tags: - Agent Profiles summary: Materialize Agent Profile description: >- Preview the launch of a profile; return a diagnostics report. Previews the stored profile ``name``, or ``body.profile`` when given (so an editor can preview before saving), with the same resolve and finalize as a launch, against the runtime this server launches into. Dangling references are reported in the body (valid=False) rather than raising — the only error statuses are 404 (unknown stored profile) and 422 (invalid draft). resolved_settings is redacted (no raw secrets). operationId: materialize_agent_profile_api_agent_profiles__name__materialize_post parameters: - in: path name: name required: true schema: maxLength: 64 minLength: 1 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ title: Name type: string requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/MaterializeAgentProfileRequest' - type: 'null' title: Body responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentProfileDiagnostics' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: MaterializeAgentProfileRequest: additionalProperties: false properties: profile: anyOf: - oneOf: - $ref: '#/components/schemas/OpenHandsAgentProfile' - $ref: '#/components/schemas/ACPAgentProfile' - type: 'null' description: >- Draft profile to evaluate instead of the stored one. The path name overrides the draft's name. title: Profile title: MaterializeAgentProfileRequest type: object AgentProfileDiagnostics: description: >- Side-effect-free report of what :func:`resolve_agent_profile` would do. Consumed by ``POST /{id}/materialize`` (#3719) and the canvas editor. The verdict (:attr:`valid`) and the dangling-ref lists match exactly what a real resolve produces; :attr:`resolved_settings` is the redacted settings dump (present only when :attr:`valid`). properties: acp_api_key_secret_name: anyOf: - type: string - type: 'null' title: Acp Api Key Secret Name acp_base_url_secret_name: anyOf: - type: string - type: 'null' title: Acp Base Url Secret Name acp_file_secret_names: items: type: string title: Acp File Secret Names type: array agent_kind: title: Agent Kind type: string dangling_mcp_server_refs: items: type: string title: Dangling Mcp Server Refs type: array dangling_meta_profile_llm_refs: items: type: string title: Dangling Meta Profile Llm Refs type: array dangling_meta_profile_ref: anyOf: - type: string - type: 'null' title: Dangling Meta Profile Ref disabled_skills: items: type: string title: Disabled Skills type: array errors: items: type: string title: Errors type: array llm_api_key_set: default: false title: Llm Api Key Set type: boolean llm_profile_ref: anyOf: - type: string - type: 'null' title: Llm Profile Ref llm_profile_resolved: default: false title: Llm Profile Resolved type: boolean mcp_server_refs: anyOf: - items: type: string type: array - type: 'null' title: Mcp Server Refs meta_profile_ref: anyOf: - type: string - type: 'null' title: Meta Profile Ref resolved_mcp_config_keys: items: type: string title: Resolved Mcp Config Keys type: array resolved_settings: anyOf: - additionalProperties: true type: object - type: 'null' title: Resolved Settings resolved_skills: items: type: string title: Resolved Skills type: array secret_refs: anyOf: - items: type: string type: array - type: 'null' title: Secret Refs unusable_tools: description: >- Selected tools the runtime cannot run. An unavailable browser is left out of the launch; any other such tool fails the launch or fails when the agent uses it. items: type: string title: Unusable Tools type: array valid: default: false title: Valid type: boolean required: - agent_kind title: AgentProfileDiagnostics type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object OpenHandsAgentProfile: additionalProperties: false description: >- ``agent_kind="openhands"`` profile — references an LLM profile by name. Mirrors the configurable surface of :class:`~openhands.sdk.settings.model.OpenHandsAgentSettings`, except the concrete ``llm`` is replaced by :attr:`llm_profile_ref` (resolved against the LLM profile store) and ``mcp_config`` by the inherited :attr:`~AgentProfileBase.mcp_server_refs`. properties: agent: default: CodeActAgent description: Agent class to build. title: Agent type: string agent_kind: const: openhands default: openhands description: >- Discriminator for the ``AgentProfile`` union. ``'openhands'`` selects the standard built-in OpenHands agent. title: Agent Kind type: string condenser: description: Condenser settings for the agent. oneOf: - $ref: '#/components/schemas/LLMSummarizingCondenserSettings' - $ref: '#/components/schemas/NoOpCondenserSettings' title: Condenser disabled_skills: description: >- Names of server-discovered skills to EXCLUDE from this agent's prompt — a deny-list over the discovered catalog. [] (the default) = all discovered skills; a listed name that is absent from the catalog is simply a no-op, so the field never fails a launch when the catalog drifts. Replaces the former allow-list ``skill_refs`` (#4017): skills are discovered from many incomplete sources, so exclusion is the only selection model that can't dangle. items: type: string title: Disabled Skills type: array enable_classify_and_switch_llm_tool: default: false description: >- Enable the built-in route_task_to_model tool, which routes the task to an LLM profile using the meta-profile named by `meta_profile_ref`. title: Enable Classify And Switch Llm Tool type: boolean id: description: >- Stable provenance handle for this profile. Conversations record this UUID; it never changes, even when the profile is renamed. format: uuid title: Id type: string llm_profile_ref: description: >- Name of the saved LLM profile to resolve for this agent. The profile itself stores no LLM credential — it lives on the referenced LLM profile. minLength: 1 title: Llm Profile Ref type: string mcp_server_refs: anyOf: - items: type: string type: array - type: 'null' description: >- Which of the user's globally configured MCP servers to expose. null = all; [] = none; a non-null list = filter to the named keys. title: Mcp Server Refs meta_profile_ref: anyOf: - minLength: 1 type: string - type: 'null' description: >- Name of the saved meta-profile the routing tool uses. The launch copies it and the LLM profiles it routes to into the agent, so a runtime without the stores can still route. null lets the tool fall back to the first meta-profile in the runtime's store. title: Meta Profile Ref name: description: Human-facing, renameable key shown in the profile picker. minLength: 1 title: Name type: string persona: anyOf: - maxLength: 65536 minLength: 1 type: string - type: 'null' description: >- Persona text that replaces OpenHands' built-in persona and coding-workflow guidance. Capability and policy guidance (memory, security policy, risk assessment, browser, external services, process management, model-specific notes) and the dynamic context are still included. None keeps the built-in persona. title: Persona revision: default: 0 description: Monotonic revision counter, bumped on each saved edit. minimum: 0 title: Revision type: integer schema_version: default: 3 minimum: 1 title: Schema Version type: integer secret_refs: anyOf: - items: type: string type: array - type: 'null' description: >- Which of the user's saved secrets to expose to this agent. null = all; [] = none; a non-null list = filter to the named keys. Strict: nothing is added back. An ACP profile must list its own provider credential to receive it. title: Secret Refs system_message_suffix: anyOf: - type: string - type: 'null' description: Optional suffix appended to the system prompt. title: System Message Suffix tool_concurrency_limit: default: 1 description: >- Maximum number of tool calls to execute concurrently per agent step. 1 = sequential (default). minimum: 1 title: Tool Concurrency Limit type: integer tools: anyOf: - items: $ref: '#/components/schemas/Tool-Input' type: array - type: 'null' description: >- Tool selection for the resolved agent. None (the default) = the server's standard tool set; [] = an explicitly bare agent; a non-empty list is used exactly as given. title: Tools verification: $ref: '#/components/schemas/ProfileVerificationSettings' description: Critic/verification policy (secret-free; no critic_api_key). required: - name - llm_profile_ref title: OpenHandsAgentProfile type: object ACPAgentProfile: additionalProperties: false description: >- ``agent_kind="acp"`` profile — names an ACP backend, stores no credential. There is no ``llm_profile_ref`` and no embedded credential: the ACP subprocess makes its own model calls, and the provider's credential (env-var name) is derived from :attr:`acp_server` via the :data:`~openhands.sdk.settings.acp_providers.ACP_PROVIDERS` registry. The value rides the conversation secrets channel, never the profile. properties: acp_args: anyOf: - items: type: string type: array - type: 'null' description: Additional arguments appended to the ACP server command. title: Acp Args acp_command: anyOf: - type: string - type: 'null' description: >- Optional explicit command to launch the ACP subprocess. Leave blank to use the default for ``acp_server``. title: Acp Command acp_model: anyOf: - type: string - type: 'null' description: >- Model identifier for the ACP server (e.g. 'claude-opus-4-8'). Leave blank to let the server pick its default. title: Acp Model acp_prompt_timeout: default: 1800 description: >- Inactivity timeout (seconds) for a single ACP prompt() round-trip; resets on every update from the server. exclusiveMinimum: 0 title: Acp Prompt Timeout type: number acp_server: default: claude-code description: >- Which ACP-compatible backend to launch. The provider's credential env-var name is derived from this via the ACP_PROVIDERS registry. enum: - claude-code - codex - gemini-cli - kimi-code - pi - opencode - custom title: Acp Server type: string acp_session_mode: anyOf: - type: string - type: 'null' description: >- Session mode ID (e.g. 'bypassPermissions'). Leave blank to auto-detect from the ACP server type. title: Acp Session Mode acp_startup_timeout: default: 90 description: >- Timeout (seconds) for ACP server startup: spawn, initialize/authenticate, and new_session()/load_session(). exclusiveMinimum: 0 title: Acp Startup Timeout type: number agent_kind: const: acp default: acp description: >- Discriminator for the ``AgentProfile`` union. ``'acp'`` selects an ACP-delegating agent. title: Agent Kind type: string id: description: >- Stable provenance handle for this profile. Conversations record this UUID; it never changes, even when the profile is renamed. format: uuid title: Id type: string mcp_server_refs: anyOf: - items: type: string type: array - type: 'null' description: >- Which of the user's globally configured MCP servers to expose. null = all; [] = none; a non-null list = filter to the named keys. title: Mcp Server Refs name: description: Human-facing, renameable key shown in the profile picker. minLength: 1 title: Name type: string revision: default: 0 description: Monotonic revision counter, bumped on each saved edit. minimum: 0 title: Revision type: integer schema_version: default: 3 minimum: 1 title: Schema Version type: integer secret_refs: anyOf: - items: type: string type: array - type: 'null' description: >- Which of the user's saved secrets to expose to this agent. null = all; [] = none; a non-null list = filter to the named keys. Strict: nothing is added back. An ACP profile must list its own provider credential to receive it. title: Secret Refs required: - name title: ACPAgentProfile type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object LLMSummarizingCondenserSettings: description: Settings for the default LLM summarizing condenser. properties: condenser_kind: const: llm_summarizing default: llm_summarizing description: >- Discriminator for the condenser settings union. ``'llm_summarizing'`` selects the default LLM summarizing condenser. openhands_settings: depends_on: [] prominence: minor title: Condenser Kind type: string enabled: default: true description: Enable conversation memory condensation. openhands_settings: depends_on: [] label: Enable memory condensation prominence: critical title: Enabled type: boolean hard_context_reset_context_scaling: default: 0.8 description: >- Factor used to reduce event string size after a hard context reset summarization failure. exclusiveMaximum: 1 exclusiveMinimum: 0 openhands_settings: depends_on: - enabled label: Hard reset scaling prominence: minor title: Hard Context Reset Context Scaling type: number hard_context_reset_max_retries: default: 5 description: Number of hard context reset attempts before raising an error. exclusiveMinimum: 0 openhands_settings: depends_on: - enabled label: Hard reset retries prominence: minor title: Hard Context Reset Max Retries type: integer keep_first: default: 2 description: Minimum number of initial events to preserve before condensation. minimum: 0 openhands_settings: depends_on: - enabled label: Keep first prominence: minor title: Keep First type: integer max_size: default: 240 description: >- Maximum number of events kept before the condenser runs. Kept on the base settings class for compatibility; concrete condenser-settings variants may opt out when this does not apply. minimum: 20 openhands_settings: depends_on: - enabled label: Max size prominence: minor title: Max Size type: integer max_tokens: anyOf: - exclusiveMinimum: 0 type: integer - type: 'null' description: >- Maximum number of tokens allowed before the condenser runs. When unset, condensation is only based on event count. openhands_settings: depends_on: - enabled label: Max tokens prominence: minor title: Max Tokens minimum_progress: default: 0.1 description: >- Minimum fraction of events that must be condensed for condensation to be considered successful. exclusiveMaximum: 1 exclusiveMinimum: 0 openhands_settings: depends_on: - enabled label: Minimum progress prominence: minor title: Minimum Progress type: number title: LLMSummarizingCondenserSettings type: object NoOpCondenserSettings: description: Settings for a condenser that leaves conversation views unchanged. properties: condenser_kind: const: no_op default: no_op description: >- Discriminator for the condenser settings union. ``'no_op'`` selects a condenser that leaves conversation views unchanged. openhands_settings: depends_on: [] prominence: minor title: Condenser Kind type: string enabled: default: true description: Enable conversation memory condensation. openhands_settings: depends_on: [] label: Enable memory condensation prominence: critical title: Enabled type: boolean title: NoOpCondenserSettings type: object Tool-Input: description: |- Defines a tool to be initialized for the agent. This is only used in agent-sdk for type schema for server use. properties: name: description: >- Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage. examples: - TerminalTool - FileEditorTool - TaskTrackerTool title: Name type: string params: additionalProperties: true description: >- Parameters for the tool's .create() method, e.g., {'working_dir': '/app'} examples: - working_dir: /workspace title: Params type: object required: - name title: Tool type: object ProfileVerificationSettings: description: >- Secret-free critic/refinement policy for a profile. The non-credential subset of :class:`~openhands.sdk.settings.model.VerificationSettings`: ``critic_api_key`` is omitted so the profile holds no secret. The critic reuses the resolved LLM profile's key (the existing ``critic_api_key=None`` behavior). properties: critic_enabled: default: false title: Critic Enabled type: boolean critic_mode: default: finish_and_message enum: - finish_and_message - all_actions title: Critic Mode type: string critic_model_name: anyOf: - type: string - type: 'null' title: Critic Model Name critic_server_url: anyOf: - type: string - type: 'null' title: Critic Server Url critic_threshold: default: 0.6 maximum: 1 minimum: 0 title: Critic Threshold type: number enable_iterative_refinement: default: false title: Enable Iterative Refinement type: boolean max_refinement_iterations: default: 3 minimum: 1 title: Max Refinement Iterations type: integer title: ProfileVerificationSettings type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.