OpenHands · simonrosenberg · Jul 14, 2026 · Jul 15, 2026
diff --git a/docs.json b/docs.json
@@ -339,6 +339,7 @@
             "pages": [
               "sdk/arch/overview",
               "sdk/arch/design",
+              "sdk/arch/agent-profiles",
               {
                 "group": "SDK Components",
                 "pages": [

@@ -0,0 +1,138 @@
+---
+title: Agent Profiles and Launch Composition
+description: How stored profiles, client-defined tools, and launch context compose a conversation agent.
+---
+
+An **Agent Profile** is a named, reusable specification for launching an agent. It stores durable user intent, such as the agent kind, referenced LLM profile, tool selection, and MCP server selection. It is not a running agent and does not contain resolved credentials.
+
+The agent server resolves a profile when a conversation starts. The client can also supply client-defined tools and deployment-specific context for that launch. The server materializes the result and persists it with the conversation.
+
+## Design Goals
+
+Agent Profiles follow four principles:
+
+- **Portable profiles:** A profile can be launched by Agent Canvas, another client application, or directly through the agent-server API.
+- **Application-neutral storage:** Profiles do not contain client-specific tools, deployment URLs, or resolved secrets unless the user explicitly selected them as profile configuration.
+- **Server-owned resolution:** The agent server resolves profile references and produces the final agent used by the conversation.
+- **Stable conversations:** A conversation resumes from its materialized agent rather than re-resolving the current version of its profile.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Modules["Server Tool Modules"] -->|register implementations| Registry["Runtime Tool Registry"]
+    Profiles["Agent Profile Store"] -->|load by profile ID| Compose["Launch Composition"]
+    Registry -->|resolve profile tools| Compose
+    Client["Client Application"] -->|profile ID| Compose
+    Client -->|client_tools JSON specs| Compose
+    Client -->|deployment context| Compose
+    Compose --> Agent["Materialized Agent"]
+    Agent --> Conversation["Persisted Conversation"]
+    Conversation -->|client-tool actions| Client
+```
+
+### Component Responsibilities
+
+| Component | Owns | Does Not Own |
+| --- | --- | --- |
+| **Server tool module and registry** | Server-executed tool names, factories, and runtime availability | Whether a profile selects a tool |
+| **Agent Profile** | Durable, secret-free agent configuration and references | Client-specific UI tools, deployment context, or resolved credentials |
+| **Client application** | Profile selection, client-executed tool definitions, and deployment context | Profile resolution or server tool defaults |
+| **Agent server** | Profile storage, validation, reference resolution, launch composition, and conversation persistence | Client-specific product behavior |
+| **Conversation** | The materialized agent, client tool specifications, and profile provenance used for resume | Live synchronization with later profile edits |
+
+## Tool Selection
+
+Registering a server tool makes its implementation available to the runtime. Registration alone does not select the tool for an agent.
+
+For an OpenHands Agent Profile, the `tools` field controls the server-executed tools selected by that profile:
+
+| Profile `tools` | Resolved Server Tools |
+| --- | --- |
+| `null` | Use the standard OpenHands tool set |
+| `[]` | Use no server tools |
+| Non-empty list | Use that list exactly |
+
+The standard tool set is independent of any profile whose name happens to be `default`. Renaming or editing that profile does not change the standard tool set.
+
+## Client-Defined Tools
+
+A client application can send JSON `client_tools` specifications when it starts a conversation. The server adds those tools after resolving the inline agent or Agent Profile. When the agent calls one, the server emits its action over the conversation event stream and the client performs the product-specific behavior.
+
+Client-defined tools do not require a Python implementation in the agent-server runtime. Their names, descriptions, parameter schemas, and annotations travel with the conversation and are restored with it.
+
+For example, Agent Canvas sends `canvas_ui_control` as a client-defined tool. Its frontend handles the resulting action by selecting a file, preview, or application tab. Another client could use the same API for a tool such as `post_on_slack` without making either tool part of the server's standard tool set.
+
+Client-defined tools are additive to the profile's `tools` field:
+
+| Profile `tools` | Resolved Server Tools | Canvas Client Tool | Materialized Tools |
+| --- | --- | --- | --- |
+| `null` | Standard OpenHands set | `canvas_ui_control` | Standard set plus `canvas_ui_control` |
+| `[]` | None | `canvas_ui_control` | `canvas_ui_control` |
+| `[{"name": "terminal"}]` | `terminal` | `canvas_ui_control` | `terminal` plus `canvas_ui_control` |
+
+<Note>
+  An explicit profile list is exact for server-executed tools. To launch a completely tool-free agent, the client must also omit `client_tools`.
+</Note>
+
+## Launch Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Client Application
+    participant Server as Agent Server
+    participant Store as Profile Store
+    participant Conversation
+
+    Client->>Server: Start with profile ID, client_tools, and launch context
+    Server->>Store: Load profile
+    Store-->>Server: Stored profile and revision
+    Server->>Server: Resolve LLM, MCP, skills, and profile tools
+    Server->>Server: Add client-defined tools
+    Server->>Server: Append deployment context
+    Server->>Conversation: Persist materialized agent and provenance
+    Server-->>Client: Conversation information
+```
+
+The launch request does not modify the stored profile. Editing a profile later also does not change conversations that were already launched from it.
+
+## Launch-Only Context
+
+Some instructions belong to the current deployment rather than a reusable profile. For example, a deployment can tell the agent how to reach runtime services that are available only for that launch.
+
+Clients send these instructions through `agent_launch_additions.system_message_suffix_append`. The server appends the value after resolving the inline agent or Agent Profile. Launch additions cannot replace the profile's LLM, tools, or other durable configuration.
+
+The server folds the suffix into the materialized agent and excludes `agent_launch_additions` from stored request metadata. This prevents the suffix from being applied twice when the conversation resumes.
+
+## Persistence and Provenance
+
+When a profile launches a conversation, the server stores:
+
+- The fully materialized agent, including resolved server tools, client tools, and launch context.
+- The client tool specifications needed to restore client-executed actions.
+- The stable profile ID and profile revision used at launch.
+- The conversation-scoped configuration and secret references needed for restore.
+
+The server does not re-resolve the profile during resume. This provides deterministic behavior when a profile is renamed, edited, or deleted after a conversation starts.
+
+Server-executed tools referenced by the materialized agent must still be available when the conversation resumes. Client-defined tools remain executable by the connected client and do not require a server-side Python module.
+
+## Compatibility and Migration
+
+Clients must only send `agent_launch_additions` to server releases that support it. When it is unavailable, a client can continue constructing its existing inline agent. The established `client_tools` API remains independent of that compatibility path.
+
+Legacy profile migration is deliberately narrow. A schema-v1, untouched revision-0 OpenHands profile named `default` that was seeded with `tools: []` migrates to `tools: null`. User-created profiles and explicit empty lists remain unchanged.
+
+Older persisted conversations can still reference server-executed tool modules that current clients no longer use. Deployments can keep those modules importable for restore while all new conversations use client-defined tools.
+
+## ACP Profiles
+
+ACP agents delegate prompt construction and tool execution to an ACP subprocess. Their tools are not resolved through the OpenHands profile tool-composition path described above. Shared profile behavior, such as stable identity, references, revision provenance, and conversation snapshots, still applies.
+
+## See Also
+
+- [Agent Architecture](/sdk/arch/agent)
+- [Tool System and MCP](/sdk/arch/tool-system)
+- [Conversation Architecture](/sdk/arch/conversation)
+- [Remote Agent Server](/sdk/guides/agent-server/overview)
+- [Manage Agent Profiles in Agent Canvas](/openhands/usage/agent-canvas/agent-profiles)
@@ -3,14 +3,14 @@
 description: Understanding the OpenHands Software Agent SDK's package structure, component interactions, and execution models.
 ---

 The **OpenHands Software Agent SDK** provides a unified, type-safe framework for building and deploying AI agents—from local experiments to full production systems, focused on **statelessness**, **composability**, and **clear boundaries** between research and deployment.

 Check [this document](/sdk/arch/design) for the core design principles that guided its architecture.

 ## Relationship with OpenHands Applications

 The Software Agent SDK serves as the **source of truth for agents** in OpenHands. The [OpenHands repository](https://github.com/OpenHands/OpenHands) provides interfaces—web app, CLI, and cloud—that consume the SDK APIs. This architecture ensures consistency and enables flexible integration patterns.
 - **Software Agent SDK = foundation.** The SDK defines all core components: agents, LLMs, conversations, tools, workspaces, events, and security policies.
 - **Interfaces reuse SDK objects.** The OpenHands GUI or CLI hydrate SDK components from persisted settings and orchestrate execution through SDK APIs.
 - **Consistent configuration.** Whether you launch an agent programmatically or via the OpenHands GUI, the supported parameters and defaults come from the SDK.

@@ -89,7 +89,7 @@
 - Perfect for prototyping and simple use cases
 - Quick setup, no Docker required

 #### Mode 2: Production / Sandboxed

 **Installation:** Install all 4 packages

@@ -131,7 +131,7 @@
 ```

 - `RemoteWorkspace` auto-spawns agent-server in containers
 - Sandboxed execution for security
 - Multi-user deployments
 - Distributed systems (e.g., Kubernetes) support

@@ -145,6 +145,7 @@
 
 **Key Components:**
 - **[Agent](/sdk/arch/agent):** Implements the reasoning-action loop
+- **[Agent Profiles](/sdk/arch/agent-profiles):** Store portable agent configuration and compose it with launch-time application context
 - **[Conversation](/sdk/arch/conversation):** Manages conversation state and lifecycle
 - **[LLM](/sdk/arch/llm):** Provider-agnostic language model interface with retry and telemetry
 - **[Tool System](/sdk/arch/tool-system):** Typed base class definitions for action, observation, tool, and executor; includes MCP integration
@@ -154,7 +155,7 @@
 - **[Condenser](/sdk/arch/condenser):** Conversation history compression for token management
 - **[Security](/sdk/arch/security):** Action risk assessment and validation before execution

 **Design:** Stateless, immutable components with type-safe Pydantic models.

 **Self-Contained:** Build and run agents with just `openhands-sdk` using `LocalWorkspace`.

@@ -184,7 +185,7 @@

 **Design:** All workspace implementations extend `RemoteWorkspace` from SDK, adding container lifecycle or API client functionality.

 **Use Cases:** Sandboxed execution, multi-user deployments, production environments.

 <Note>
 For full list of implemented workspaces, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace).

@@ -11,8 +11,8 @@

 The Tool System has four primary responsibilities:

 1. **Type Safety** - Enforce action/observation schemas via Pydantic models
 2. **Schema Generation** - Auto-generate LLM-compatible tool descriptions from Pydantic schemas
 3. **Execution Lifecycle** - Validate inputs, execute logic, wrap outputs
 4. **Tool Registry** - Discover and resolve tools by name or pattern

@@ -64,11 +64,11 @@
 | Component | Purpose | Design |
 |-----------|---------|--------|
 | **[`ToolBase`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Abstract base class | Generic over Action and Observation types, defines abstract `create()` |
 | **[`ToolDefinition`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Concrete tool class | Can be instantiated directly or subclassed for factory pattern |
 | **[`Action`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/schema.py)** | Input model | Pydantic model with `visualize` property |
 | **[`Observation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/schema.py)** | Output model | Pydantic model with `to_llm_content` property |
 | **[`ToolExecutor`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Execution interface | ABC with `__call__()` method, optional `close()` |
 | **[`ToolAnnotations`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/tool.py)** | Behavioral hints | MCP-spec hints (readOnly, destructive, idempotent, openWorld) |
 | **[`Tool` (spec)](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/spec.py)** | Tool specification | Configuration object with name and params |
 | **[`ToolRegistry`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/tool/registry.py)** | Tool discovery | Resolves Tool specs to ToolDefinition instances |

@@ -141,8 +141,8 @@
 ```

 **Components:**
 1. **Action** - Pydantic model with `visualize` property for display
 2. **Observation** - Pydantic model with `to_llm_content` property for LLM
 3. **ToolExecutor** - Stateless executor with `__call__(action) → observation`
 4. **ToolDefinition** - Direct instantiation with executor instance

@@ -218,7 +218,7 @@

 ### Tool Annotations

 Tools include optional `ToolAnnotations` based on the [Model Context Protocol (MCP) spec](https://github.com/modelcontextprotocol/modelcontextprotocol) that provide behavioral hints to LLMs:

 | Field | Meaning | Examples |
 |-------|---------|----------|
@@ -229,12 +229,14 @@

 **Key Behaviors:**
 - [LLM-based Security risk prediction](/sdk/guides/security) automatically added for tools with `readOnlyHint=False`
 - Annotations help LLMs reason about tool safety and side effects

 ### Tool Registry
 
 The registry enables **dynamic tool discovery** and instantiation from tool specifications:
 
+Registration makes a server tool implementation available; it does not select the tool for an agent. [Agent Profile launch composition](/sdk/arch/agent-profiles) explains how profile-selected server tools compose with client-defined tools.
+
 ```mermaid
 %%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%%
 flowchart LR
@@ -263,7 +265,7 @@
 2. **Resolver Lookup** - Registry finds the registered resolver for the tool name
 3. **Factory Invocation** - Resolver calls the tool's `.create()` method with params and conversation state
 4. **Instance Creation** - Tool instance(s) are created with configured executors
 5. **Agent Usage** - Instances are added to the agent's tools_map for execution

 **Registration Types:**

@@ -296,7 +298,7 @@
 **Benefits:**
 - **Separation of Concerns** - Public API separate from implementation
 - **Avoid Circular Imports** - Import `impl` only inside `create()` method
 - **Consistency** - All tools follow same structure for discoverability

 **Example Reference:** See [`terminal/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-tools/openhands/tools/terminal) for complete implementation

@@ -352,10 +354,10 @@
 |-----------|---------|--------|
 | **[`MCPClient`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/client.py)** | MCP server connection | Extends FastMCP with sync/async bridge |
 | **[`MCPToolDefinition`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Tool wrapper | Wraps MCP tools as SDK `ToolDefinition` with dynamic validation |
 | **[`MCPToolExecutor`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Execution handler | Bridges agent actions to MCP tool calls via MCPClient |
 | **[`MCPToolAction`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Generic action wrapper | Simple `dict[str, Any]` wrapper for MCP tool arguments |
 | **[`MCPToolObservation`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/definition.py)** | Result wrapper | Wraps MCP tool results as observations with content blocks |
 | **[`_create_mcp_action_type()`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/mcp/tool.py)** | Dynamic schema | Runtime Pydantic model generated from MCP `inputSchema` for validation |

 ### Sync/Async Bridge

@@ -428,7 +430,7 @@
   - Wraps the MCP tool metadata in `MCPToolDefinition`
   - Uses generic `MCPToolAction` as the action type (NOT dynamic models yet)
 5. **Add to Agent** - All `MCPToolDefinition` instances are added to agent's `tools_map` during `initialize()` (bypasses ToolRegistry)
 6. **Lazy Validation** - Dynamic Pydantic models are generated lazily when:
   - `action_from_arguments()` is called (argument validation)
   - `to_openai_tool()` is called (schema export to LLM)

@@ -439,7 +441,7 @@
 | `name` | Tool name (stored in `MCPToolDefinition`) | Discovery, execution |
 | `description` | Tool description for LLM | Discovery, LLM prompt |
 | `inputSchema` | Stored in `mcp_tool.inputSchema` | Lazy model generation |
 | `inputSchema` fields | Converted to Pydantic fields via `Schema.from_mcp_schema()` | Validation, schema export |
 | `annotations` | Mapped to `ToolAnnotations` | Security analysis, LLM hints |

 ### MCP Server Configuration
@@ -500,18 +502,18 @@
 ```

 **Relationship Characteristics:**
 - **Native → Registry → tools_map**: Native tools resolved via `ToolRegistry`
 - **MCP → tools_map**: MCP tools bypass registry, added directly during `initialize()`
 - **tools_map → LLM**: Generate schemas describing all available capabilities
 - **Agent → tools_map**: Execute actions, receive observations
 - **tools_map → Conversation**: Read state for context-aware execution
 - **tools_map → Security**: Tool annotations inform risk assessment

 ## See Also

 - **[Agent Architecture](/sdk/arch/agent)** - How agents select and execute tools
 - **[Events](/sdk/arch/events)** - ActionEvent and ObservationEvent structures
 - **[Security Analyzer](/sdk/arch/security)** - Action risk assessment
 - **[Skill Architecture](/sdk/arch/skill)** - Embedding MCP configs in repository skills
 - **[Custom Tools Guide](/sdk/guides/custom-tools)** - Building your own tools
 - **[FastMCP Documentation](https://gofastmcp.com/)** - Underlying MCP client library