# How the `agent_onboarding` Module Guides New Agents Through Activation > Discover how the agent_onboarding module automates new LoopX agent activation with identity metadata, installation commands, and runtime instructions. Streamline your onboarding process today. - Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx) - Tags: how-to-guide - Published: 2026-09-02 --- **The `agent_onboarding` module synthesizes a versioned onboarding packet containing identity metadata, host-surface installation commands, and runtime instructions to automate and standardize the activation of new LoopX agents.** The `huangruiteng/loopx` repository provides a declarative framework for agent orchestration, where the **`agent_onboarding`** package ([`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py)) encapsulates the entire workflow required to transform a fresh agent definition into a runnable, configured entity. Instead of manual configuration, the module programmatically generates deterministic activation scripts that handle environment preparation, capability registration, and runtime initialization. ## Core Architecture of the Onboarding Packet The onboarding process centers on a **packet**—a self-contained data structure that aggregates everything required to activate an agent. This design ensures that agent activation is reproducible and version-controlled. ### Versioned Schema Definition At the foundation of the module lies a strict schema contract. The constant **`SCHEMA_VERSION = "loopx_agent_onboarding_v0"`** (defined at line 31 of [`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py)) guarantees forward-compatible serialization of onboarding data. This versioning ensures that packets generated by older CLI versions remain interpretable by newer runtime environments, preventing breaking changes during the activation workflow. ### Packet Construction with `build_agent_onboarding_packet()` The primary entry point for programmatic onboarding is **`build_agent_onboarding_packet()`** (lines 386–440). This function aggregates the complete activation context by collecting: - **Agent Identity**: A fresh UUID or existing agent ID that uniquely identifies the entity within the control plane. - **Host-Surface Install Command**: The specific CLI fragment required to prepare the runtime environment (e.g., `loopx install-surface zcode`). - **Scheduler Binding**: Metadata instructing the control plane how to route tasks to this specific agent instance. - **Skill-Delivery Contract**: A JSON specification describing which capabilities (skills) the agent will advertise to the system. This function returns a structured dictionary that serves as the single source of truth for subsequent activation steps. ## Generating Activation Commands The module abstracts low-level CLI details by generating ready-to-execute command fragments tailored to specific host surfaces like *zcode*, *agy*, or *gemini*. ### Surface Installation via `_surface_install_command()` The helper function **`_surface_install_command()`** (lines 85–108) constructs the installation payload for the agent's runtime environment. It returns a deterministic CLI string—such as `loopx install-surface zcode`—that installs the necessary host surface without requiring users to memorize surface-specific syntax. This encapsulation ensures that the correct runtime dependencies are present before the agent attempts to start. ### Runtime Launch with `_start_instruction()` Once the surface is prepared, **`_start_instruction()`** (lines 109–131) generates the execution command that actually launches the agent. This instruction bundles the agent ID, host surface flags, and entry-point arguments into a single executable statement (e.g., `loopx run-agent --agent-id --host-surface zcode`), ensuring the agent initializes with its registered configuration. ## Skill Registration and Capability Contracts Agent capabilities are not hardcoded but declared through a dynamic contract system that integrates with the LoopX control plane. ### Defining Capabilities with `_skill_delivery_contract()` The function **`_skill_delivery_contract()`** (lines 132–159) builds a JSON contract specifying which skills the agent provides. This contract is consumed by the `loopx` runtime during activation to register the agent's capabilities in the scheduler. By externalizing skill definitions into the onboarding packet, the module enables dynamic capability discovery without requiring code changes to the control plane. ## Rendering User-Facing Activation Guides While the packet provides machine-readable instructions, the module also generates human-readable documentation to guide users through manual activation. ### Markdown Output via `render_agent_onboarding_markdown()` The function **`render_agent_onboarding_markdown()`** (lines 544–580) converts the structured packet into a step-by-step markdown document. This output includes: 1. The surface installation command. 2. The agent start instruction. 3. The skill-delivery contract for verification. When users invoke `loopx agent-onboard ... --format markdown`, the CLI renders this document, providing copy-paste-ready instructions that ensure consistent activation across different environments. ## CLI Integration and Entry Points The onboarding logic is exposed through the LoopX command-line interface via **[`loopx/cli_commands/starter_bootstrap.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/cli_commands/starter_bootstrap.py)**. The command `loopx agent-onboard` (implemented at lines 74–89) invokes `build_agent_onboarding_packet()` and formats the output according to the `--format` flag—returning either raw JSON for automation pipelines or rendered markdown for human operators. This CLI wrapper bridges the gap between the programmatic packet API and end-user workflows. ## Validation Through Testing The activation flow is validated by integration tests that verify each component of the packet. The test suite in **[`tests/test_zcode_host_surface.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_zcode_host_surface.py)** asserts that generated install commands correctly prepare the *zcode* surface (see lines 47–56), while **[`tests/test_host_loop_activation.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_host_loop_activation.py)** performs end-to-end verification that packets translate into valid runtime configurations. These tests serve as executable specifications, ensuring that changes to the onboarding module maintain backward compatibility with existing agent types. ## Summary - The **`agent_onboarding`** module creates **versioned, deterministic packets** (`SCHEMA_VERSION = "loopx_agent_onboarding_v0"`) that encapsulate all metadata required for agent activation. - **`build_agent_onboarding_packet()`** aggregates agent identity, surface installation commands, scheduler bindings, and skill contracts into a single deployable artifact. - **Surface-specific commands** are generated by `_surface_install_command()` and `_start_instruction()`, abstracting runtime preparation and launch details. - **Human-readable guides** are produced by `render_agent_onboarding_markdown()`, enabling manual activation workflows via the `loopx agent-onboard --format markdown` CLI command. - The implementation is validated by **[`tests/test_zcode_host_surface.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_zcode_host_surface.py)** and related integration tests that enforce contract correctness across different host surfaces. ## Frequently Asked Questions ### What is the schema version used in the agent_onboarding module? The module declares **`SCHEMA_VERSION = "loopx_agent_onboarding_v0"`** at line 31 of [`loopx/agent_onboarding.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/agent_onboarding.py). This constant ensures that onboarding packets remain forward-compatible, allowing newer LoopX runtimes to correctly interpret packets generated by older CLI versions. ### How does the module handle different host surfaces like zcode or agy? The module uses **`_surface_install_command()`** (lines 85–108) to generate surface-specific CLI fragments. By passing the `agent_type` parameter (e.g., `"zcode"`, `"agy"`, or `"gemini"`) to `build_agent_onboarding_packet()`, the function returns the appropriate `loopx install-surface` command for that specific runtime environment. ### What information does the skill delivery contract contain? The **`_skill_delivery_contract()`** function (lines 132–159) generates a JSON structure that declares which capabilities the agent will provide to the LoopX control plane. This contract is consumed during activation to register the agent's skills with the scheduler, enabling dynamic task routing without requiring manual capability configuration. ### How can I generate an onboarding packet programmatically? Import `build_agent_onboarding_packet` from `loopx.agent_onboarding` and call it with your project and agent type parameters. The function returns a dictionary containing the complete activation context, which you can then pass to `render_agent_onboarding_markdown()` to generate user-facing instructions or serialize to JSON for automated deployment pipelines.