Principle:OpenHands OpenHands Conversation Creation
| Knowledge Sources | |
|---|---|
| Domains | Platform_Integration, Webhook_Processing |
| Last Updated | 2026-02-11 21:00 GMT |
Overview
Conversation creation is the session initialization pattern that establishes an isolated execution context for an AI agent task triggered by a webhook event.
Description
After a webhook event has been validated, parsed, and acknowledged, the system must create a conversation -- an isolated execution session in which an AI agent will work on the task. The conversation serves as the bridge between the external platform event (a GitHub issue, a PR comment) and the internal agent execution environment (a sandbox with access to the repository, tools, and language models).
Conversation creation involves:
- Metadata assembly -- Collecting all information needed to initialize the agent session: the repository to clone, the branch to work on, the issue description, user identity, and configuration flags.
- Version routing -- Directing the conversation to the appropriate execution backend. Systems often maintain multiple versions of the agent runtime (e.g., v0 and v1), and the routing decision may depend on feature flags, user preferences, or issue characteristics.
- Context bridging -- Translating platform-specific concepts (GitHub issue numbers, PR review threads) into platform-agnostic agent instructions that the execution backend can process.
The conversation is the fundamental unit of agent work: it has a unique identifier, a lifecycle (created, running, completed, failed), and produces artifacts (code changes, comments, status updates) that are posted back to the originating platform.
Usage
Apply this pattern when:
- An external event should trigger an isolated agent execution session
- The agent needs repository access, user context, and task description packaged together
- Multiple execution backends exist and routing logic is needed
- The system must track the lifecycle of each agent task for observability and billing
Theoretical Basis
1. Session Initialization Pattern
Conversation creation follows the session initialization pattern from distributed systems. A session encapsulates all state needed for a unit of work:
Session = {
id: UUID,
created_at: Timestamp,
status: CREATED | RUNNING | COMPLETED | FAILED,
context: TaskContext,
artifacts: List[Artifact],
}
The session provides isolation: each conversation runs independently, with its own cloned repository, sandbox environment, and agent state. Failures in one conversation do not affect others.
2. Context Object Pattern
The metadata assembled during conversation creation forms a context object -- a single structure that carries all the information needed by downstream components:
ConversationContext = {
repo_url: str,
branch: str,
issue_number: int,
issue_title: str,
issue_body: str,
user_identity: UserInfo,
permissions: PermissionSet,
config: AgentConfig,
}
The context object decouples the collection of information (which requires platform-specific API calls) from the consumption of that information (which is platform-agnostic).
3. Strategy Pattern for Version Routing
When multiple execution backends are available, the routing decision follows the Strategy pattern:
create_conversation(context, version_flag):
if version_flag == V1:
return create_v1_conversation(context)
else:
return create_v0_conversation(context)
Each strategy implements the same interface but uses a different backend, API, or execution model. The routing decision can be based on:
- Feature flags (per-user or per-organization)
- Issue characteristics (complexity, repository size)
- System load (directing traffic away from overloaded backends)
4. Idempotent Creation
Conversation creation should be idempotent with respect to the triggering event. If the same webhook event is delivered twice (due to retries), the system should not create two conversations. This is achieved by using the event's unique identifier as a deduplication key:
create_if_not_exists(event_id, context):
if conversation_exists(event_id):
return get_conversation(event_id)
else:
return create_conversation(event_id, context)