Integrate AI Coding Agents

Prepare the deployment environment

• Pilot release — Use a LoongSuite Pilot release that includes hook install and its matching container entrypoint. The Kubernetes init image must also include /mnt/pilot/bin/loongsuite-pilot.

• Base image — A glibc-based Linux image, such as Debian or Ubuntu, is recommended. The shared Kubernetes runtime also requires compatible C/C++ runtime libraries in the business image. Validate runtime and dependency compatibility separately for musl-based images such as Alpine.

• Shell — start.sh requires Bash. The container entrypoint requires a POSIX shell.

• User and directories — Run Pilot, the hook installation command, and the agent as the same user, with the same HOME and agent configuration directory. The agent configuration directory and the Pilot data directory must be writable.

• Integration parameters — Obtain log and trace integration parameters from the AgentLoop console. Ensure that the container can reach the reporting endpoints.

  Container-mode installation does not register host services or start collection during the image build, and disables automatic updates. To upgrade, rebuild the business image or update the Kubernetes init image version.

Prepare the reporting configuration

The log and trace parameters are the same as for local installations. For containers, mount the configuration at runtime. Save the following example as pilot-config.json and replace the placeholders with values from the AgentLoop console.

{
  "collectLog": true,
  "collectTrace": true,
  "autoUpdate": { "enabled": false },
  "sls": {
    "mode": "webtracking",
    "endpoint": "your_SLS_endpoint",
    "project": "your_SLS_Project_name",
    "logstore": "your_SLS_Logstore_name"
  },
  "cms": {
    "licenseKey": "your_Trace_License_Key",
    "endpoint": "your_Trace_endpoint",
    "workspace": "your_Trace_workspace"
  },
  "serviceNamePrefix": "your_service_name_prefix"
}

This example uses WebTracking. Enable WebTracking on the target Logstore. For other authentication methods, configure sls for the corresponding integration method. To collect only logs or only traces, set the other collect option to false.

Provide files that contain credentials through runtime mounts or Kubernetes Secrets. Do not include them in the business image.

Method 1: Integrate Pilot into the business image

Use this method when you can modify the business image. Install the agent first, then install Pilot with container mode and the agent IDs to collect.

The following example uses Claude Code:

FROM node:22-bookworm-slim

ARG PILOT_VERSION
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl bash \
    && rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code \
    && useradd --create-home --shell /bin/bash agent

USER agent
ENV HOME=/home/agent
ENV PATH=/home/agent/.local/bin:$PATH
RUN mkdir -p /home/agent/.claude

RUN test -n "$PILOT_VERSION" \
    && curl -fsSL https://aliyun-observability-release-cn-shanghai.oss-cn-shanghai.aliyuncs.com/loongsuite-pilot/installer.sh \
       -o /tmp/loongsuite-pilot-installer.sh \
    && bash /tmp/loongsuite-pilot-installer.sh install \
       --mode container --agents claude-code --version "$PILOT_VERSION"

ENV AGENT_DATA_COLLECTION_CONFIG=/etc/loongsuite-pilot/config.json
ENTRYPOINT ["/home/agent/.loongsuite-pilot/entrypoint.sh"]
CMD ["claude", "-p", "hello"]

docker build --build-arg PILOT_VERSION='<Pilot_version>' -t my-agent:instrumented .
docker run --rm --init --stop-timeout 30 \
  --mount "type=bind,src=$(pwd)/pilot-config.json,dst=/etc/loongsuite-pilot/config.json,readonly" \
  my-agent:instrumented

The agent user in the container must be able to read pilot-config.json. Supply the agent's model-service credentials through its usual authentication mechanism.

During the build, the installer checks and deploys collection configuration for the specified agents. Deployment failure causes the build to fail. At container startup, the entrypoint reads LOONGSUITE_PILOT_AGENTS, or uses the agent list saved during the build if this variable is unset. It checks and installs hooks before starting the collector and the business process. Unchanged configuration returns up-to-date.

Generate agent configuration after container startup

If the business command generates or overwrites configuration, skip entrypoint injection and invoke installation after generation. Replace the startup settings in the Dockerfile with the following settings:

ENV LOONGSUITE_PILOT_AGENTS=none
CMD ["sh", "-c", "/app/render-settings.sh && { loongsuite-pilot hook install --agents claude-code || true; } && exec claude -p \"$TASK\""]

/app/render-settings.sh is your configuration generation script, and TASK contains the task supplied at runtime. The value none skips entrypoint injection. The explicit --agents claude-code argument takes precedence over the environment variable, so the command after rendering still executes.

The || true suffix allows the business process to start if hook installation fails. To require successful installation before a task runs, remove || true; a nonzero exit code then prevents the agent from starting.

Method 2: Use a Kubernetes webhook

Use this method when the LoongSuite Pilot webhook is deployed and enabled in the cluster. The webhook injects the init container, shared volume, interpreter startup configuration, and shutdown hook. Set agentLoopSpaceName to the identifier associated with the integration task.

To use default injection, add the following labels to the Pod template of the workload:

spec:
  template:
    metadata:
      labels:
        loongsuitePilotAutoEnable: "on"
        agentLoopSpaceName: "<integration_workspace_ID>"
        agentLoopAgents: "claude-code"

The agentLoopAgents label limits the target agents. Separate multiple IDs with commas. The default path installs hooks early when an eligible Node/Bun or CPython process starts.

Choose the injection time explicitly

If configuration must be rendered first, or you use Hermes Agent or DeepSeek Harness, use start.sh to run the complete installation before the business process starts. The following is a configuration fragment for an existing Deployment. Keep the Pod template labels and change the startup command of the business container:

spec:
  template:
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: agent
          image: my-agent:latest
          command: ["/bin/sh", "-ec"]
          args:
            - |
              /app/render-settings.sh
              exec /mnt/pilot/start.sh --agents=claude-code -- claude -p "$TASK"
          env:
            - name: TASK
              value: "review this PR"

If configuration is already available, use the following settings:

command: ["/mnt/pilot/start.sh"]
args: ["--agents=claude-code", "--", "claude", "-p", "hello"]

When an agent list is specified, start.sh invokes the complete installation flow. With the webhook, keep its reporting configuration and collector startup mechanism; no additional PILOT_ENABLE_DAEMON setting is needed. Preserve the environment variables and preStop injected by the webhook.

Method 3: Configure a Kubernetes init container manually

Use this method when the cluster has no webhook and you want to provide the Pilot runtime through a shared volume. Use an init image that includes this capability to copy the runtime to the volume, then execute start.sh in the business container.

Create a Secret from the reporting configuration described in "Prepare the reporting configuration". The Secret and the workload must be in the same namespace:

kubectl create secret generic pilot-config \
  --from-file=config.json=pilot-config.json

The following Job template runs a one-off task:

apiVersion: batch/v1
kind: Job
metadata:
  name: pilot-agent-demo
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      terminationGracePeriodSeconds: 30
      volumes:
        - name: pilot-runtime
          emptyDir: {}
        - name: pilot-config
          secret:
            secretName: pilot-config
      initContainers:
        - name: pilot-init
          image: <Pilot_init_image>:<version>
          volumeMounts:
            - name: pilot-runtime
              mountPath: /mnt/pilot
      containers:
        - name: agent
          image: my-agent:latest
          command: ["/mnt/pilot/start.sh"]
          args: ["--agents=claude-code", "--", "claude", "-p", "hello"]
          env:
            - name: PILOT_ENABLE_DAEMON
              value: "true"
            - name: LOONGSUITE_PILOT_DATA_DIR
              value: /mnt/pilot/data
            - name: AGENT_DATA_COLLECTION_CONFIG
              value: /etc/loongsuite-pilot/config.json
          volumeMounts:
            - name: pilot-runtime
              mountPath: /mnt/pilot
            - name: pilot-config
              mountPath: /etc/loongsuite-pilot
              readOnly: true
          lifecycle:
            preStop:
              exec:
                command: ["/mnt/pilot/prestop.sh"]

PILOT_ENABLE_DAEMON=true starts the collector without a webhook. The preStop hook gives the collector time to send buffered data before shutdown. The runtime and the business image must have compatible CPU architectures and runtime libraries.

If agent configuration is generated at runtime, change the startup command to render configuration and then execute start.sh, as shown in Method 2.

Specify configuration directories and multiple identities

If the same agent uses multiple configuration directories, invoke installation once for each directory after configuration generation and before the corresponding agent process starts:

loongsuite-pilot hook install \
  --agents claude-code --home claude-code=/workspace/claude-profile --json

The --home option applies to agents whose hook or plugin configuration paths can be relocated. It is not a universal option for every agent. For Hermes Agent and DeepSeek Harness, set HERMES_HOME and DSH_HOME as required before installing by agent ID.

For example, to register a Grok Build identity directory using the shared Kubernetes runtime, run the following command:

/mnt/pilot/bin/loongsuite-pilot hook install \
  --agents grok-build \
  --home "grok-build=/workspace/.grok/u/<identity_directory>" \
  --json

Run the command separately for each identity. It writes hook registration configuration to hooks/loongsuite-pilot.json under that directory and creates missing directories. Grok reads this file to determine which script to run for an event; collected data is written separately to the Pilot data directory. Each identity has its own registration file. Installing for another identity does not replace an existing identity's file.

Operational recommendations

• Use an explicit agent list for acceptance checks and critical tasks. Without a list, hook install detects all installed agents. Only the exact value none skips installation; unset values, empty strings, and the literal null all mean full detection.

• When the container identity can be determined, a successful named installation restricts collection deployment to agents already installed successfully and agents recorded during the image build. To add another agent later, invoke hook install again with its ID.

• For Docker, use --init --stop-timeout 30. For Kubernetes, preserve the shutdown hook and set an appropriate terminationGracePeriodSeconds. The grace period must cover business-process shutdown and collector buffer delivery; 30 seconds is an example value.

• Avoid the Kubernetes postStart hook for injection. It runs concurrently with the business entrypoint and cannot guarantee that installation finishes first.

• After a template overwrites configuration, install hooks again and start a new agent process. Background repair cannot guarantee that a running process reloads configuration.

Check the local service status

Run the following commands to check the LoongSuite Pilot service status:

loongsuite-pilot status
loongsuite-pilot info

Check the local collection output

macOS / Linux

ls ~/.loongsuite-pilot/logs/output
tail -f ~/.loongsuite-pilot/logs/output/*.jsonl

Windows

Get-ChildItem "$env:USERPROFILE\.loongsuite-pilot\logs\output"

Get-ChildItem "$env:USERPROFILE\.loongsuite-pilot\logs\output\*.jsonl" |
  Sort-Object LastWriteTime |
  Select-Object -Last 1 |
  Get-Content -Wait

If new events appear in the local output directory, the AI Coding Agent collection pipeline is working.

Check the AgentLoop console

After you trigger a new AI Coding Agent activity, go back to the AgentLoop console to check the data status of the corresponding integration task. Data arrival may be delayed due to local batch sending and backend processing.

Verify container integration

1. Check hook registration in the business container. For image integration, run the following command:

   loongsuite-pilot hook status --agents claude-code --json

   kubectl exec '<Pod_name>' -c agent -- \
     /mnt/pilot/bin/loongsuite-pilot hook status --agents claude-code --json

2. Inspect the result for the target agent. The installation status ok or up-to-date indicates that registration is complete. On failure, use reason and hint to correct the issue. The status skipped means that installation was skipped. Full detection may return no agent results if no agents are found, so specify the target ID during acceptance checks.

3. Start a new agent session and verify that logs or traces arrive in the AgentLoop console. The hook status command checks registration files; it does not verify that the agent loaded the configuration or that the reporting endpoint is reachable.

4. For troubleshooting, inspect last-hook-install.json and logs/ in the Pilot data directory. The default directory is ~/.loongsuite-pilot in the runtime user's home directory. The manual init container example uses /mnt/pilot/data.

Verify agent collection

If the expected agent has no data, check the following:

1. Make sure that the target agent is installed and has been used at least once.

2. Make sure that the agent is not set to off in the agent access control file. The default path is ~/.loongsuite-pilot/agent-control.json on macOS/Linux and C:\Users\<username>\.loongsuite-pilot\agent-control.json on Windows.

3. Make sure that the agent is not set to "enabled": false in the configuration file. The default path is ~/.loongsuite-pilot/config.json on macOS/Linux and C:\Users\<username>\.loongsuite-pilot\config.json on Windows.

4. After you modify the configuration, run loongsuite-pilot restart.

5. Trigger a new agent activity and then check the local output or the AgentLoop console.

What do I do if the expected agent is not found?

Make sure that the target agent is installed, has been used at least once, and is not disabled in agent-control.json or config.json. After you modify the configuration, run loongsuite-pilot restart. On macOS/Linux, the default configuration directory is ~/.loongsuite-pilot/. On Windows, the default directory is C:\Users\<username>\.loongsuite-pilot\.

What do I do if there is no new data locally?

Make sure that LoongSuite Pilot is running. After the service starts, trigger a new AI Coding Agent activity and then check the local JSONL output directory. The default path is ~/.loongsuite-pilot/logs/output/ on macOS/Linux and C:\Users\<username>\.loongsuite-pilot\logs\output\ on Windows.

What do I do if there is no data in the AgentLoop console?

First, check whether new events exist in the local output. If local events exist but are not displayed in the console, refresh the console later or verify that the installation command corresponds to the current AgentLoop integration task.

How do I enable data masking?

Modify the mask section in the local configuration file, save the file, and then run loongsuite-pilot restart. The default configuration file path is ~/.loongsuite-pilot/config.json on macOS/Linux and C:\Users\<username>\.loongsuite-pilot\config.json on Windows.

What do I do if Pilot runs in a container but the first session has no data?

Check whether hooks were installed before the agent read its configuration. If the business startup script generates or overwrites configuration, run hook install after generation and then start the agent. Verify with a new session. Writing registration files after a completed session does not by itself recover that session's data.

Why do Hermes Agent and DeepSeek Harness miss startup data when only webhook labels are configured?

The webhook's default early injection covers hooks and configuration-based plugin injection. The Hermes directory plugin and the DeepSeek Harness YAML patch require the complete deployment flow. Use start.sh --agents=<agent_ID> -- <original_business_command> to deploy before the agent process starts.

Why is there no data in AgentLoop after hook install succeeds?

Success indicates that the installation configuration processed by the command was written or already current. Also verify that the target agent reads that directory, new events have been generated, the collector is running, and reporting configuration, network access, and authentication are valid. Specify the target with --agents and inspect its result rather than treating skipped installation or an absent target as successful integration.

What do I do if the agent configuration directory in the container is not the default?

For agents that support configuration relocation, use hook install --agents <agent_ID> --home <agent_ID>=<directory>. Claude Code also supports --config-dir <directory>. For multiple Grok identities, invoke the command separately for each identity directory. Run installation with the same user and directory configuration as the agent, before the agent starts.