A Conversation Is a Runtime Contract

In OpenHands Agent Canvas, creating a conversation is the moment when a user’s intention becomes a concrete agreement with a backend. This chapter follows what that agreement must establish—agent, model or profile, workspace, tools, context, credentials, and confirmation behavior—and then traces how the agreement becomes a ready session, a stream of events, and a set of visible work surfaces. The practical result is a way to tell whether a conversation problem comes from request assembly, runtime readiness, workspace authority, or event transport.

What the start request has to establish

A chat interface can make “start” look like one action. The backend needs a much more specific set of facts before an agent can do useful work. It needs to know which execution agent to run, which model or saved profile supplies that agent, where the workspace is located, what message begins the task, which tools and plugins are available, how much confirmation the agent needs, and what context should be loaded around the project. These facts are not a checklist for its own sake. Each one answers a different question about authority or behavior.

The selected backend is the first condition. Canvas builds a local request through the Agent Server client when the active backend is local. It builds a different application-level request for Cloud. The request is therefore not a universal conversation object that can be sent unchanged to any host. It is an adaptation of the same user intent to the lifecycle and contract of the selected runtime.

For a local conversation, Canvas reads the active settings and, when relevant, the available agent profiles. It can send an inline agent configuration or identify a profile that the server resolves. It combines the initial user message with any conversation instruction, selects a workspace, and decides whether the runtime should use a new worktree or an explicitly selected repository. Plugins and workspace hooks can be included when the user’s context calls for them. The request also carries behavior such as confirmation policy, maximum iterations, stuck detection, automatic titling, and client tools that let the agent interact with the Canvas surface.

The important point is not the number of fields. It is the relationship among them. A model choice without a valid credential cannot produce a useful run. A valid credential attached to a workspace the Agent Server cannot write is not enough. A workspace and model without the intended tool set can yield an agent that responds but cannot perform the requested operation. Canvas assembles these dependencies before the server starts the conversation so that the runtime receives one coherent description rather than a sequence of guesses from individual screens.

Workspace selection deserves special attention because paths are physical facts, not abstract labels. A repository chosen in the browser may be represented by an absolute path on the machine where the Agent Server runs, while a default workspace may need to be resolved relative to the backend’s own home. Canvas distinguishes an explicit workspace selection from a default that should be anchored by the active backend.