How the `agent_onboarding` Module Guides New Agents Through Activation

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) 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) 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 <uuid> --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.

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 asserts that generated install commands correctly prepare the zcode surface (see lines 47–56), while 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}