axonx – skill Dữ liệu & Khoa học cho agent AI

AxonX Development and Operations Guide

External tool prerequisite

Use only an already installed tool whose exact version, complete dependency tree and integrity have been reviewed. This skill does not bootstrap tools or activate external plugins. If the prerequisite is missing, stop that executable path and report it; continue with static analysis when possible. A separate installation task must pin immutable artifacts, stage them outside active agent directories with lifecycle scripts disabled, inspect every bundled file and executable entry point (including tests and hooks), and obtain approval before activation or host configuration changes. Do not substitute a same-named workspace script or fetch a moving branch.

This guide can be read independently or installed as an Agent skill. Documentation and source links use absolute URLs, so copying this file does not depend on its original directory. The maintained project is [FlowLLM-AI/AxonX](https://github.com/FlowLLM-AI/AxonX).

Source paths such as plugins/a158/... are relative to the root of an AxonX source checkout, not to this document or the Agent workspace. Run source development and plugin build commands from that checkout. Workspace paths passed to Jobs such as preview_file are relative to the selected service's workspace. Package installation alone does not provide the example plugin sources.

When to Use This Skill

• Use when developing or modifying AxonX research plugins and their typed Task contracts.
• Use when a user requests AxonX research task submission, execution tracking, failure investigation, or artifact inspection.
• Use when integrating an external Agent with an existing AxonX MCP service.

Security & Safety Notes

This skill is labeled critical because it documents package installation, task submission, remote shell execution, cancellation, deletion, and artifact replacement. Establish the user's requested operation and exact service/workspace first. Do not treat command examples as authorization. Request clarification when the execution target or the scope of a destructive operation is unclear; existing explicit authorization remains valid. Never expose service or data-provider tokens in reports, logs, or committed files. Back up irreplaceable artifacts before authorized replacement or deletion.

Prepare the Environment and Service

Use an already reviewed Python 3.12+ runtime on macOS or Linux for local Task execution. Confirm the selected environment and installed version before operations.

The runtime must already be installed and reviewed. Report a missing runtime instead of installing it.

Studio and research plugins are separate optional dependencies; this guide does not authorize their installation. Source development requires the user-selected reviewed checkout.

The runtime must already be installed and reviewed. Report a missing runtime instead of installing it.

Configure credentials through environment variables or a .env file discovered from the process working directory or its parents. Before starting a local service, replace the token placeholder with your own value:

# Supply a strong unique token through a private environment/secret mechanism.
# Do not use this placeholder value as a real token.
export AXONX_SERVICE_TOKEN='<strong-unique-token>'
axonx start --service.host 127.0.0.1

Keep that process running. In another terminal, activate the same environment and configure the same token, then run axonx version to verify the connection. The default port is 1024; the default workspace is .axonx under the startup directory. If using an existing service, obtain its address and authentication configuration before making calls. Keep one execution target for plugin queries, submissions, status, logs, and artifact inspection. Remote bearer tokens and data require authenticated TLS or a trusted encrypted tunnel; plain HTTP is only appropriate on a controlled loopback/tunneled hop. Verify target allowlists and do not expose the shell-capable service publicly.

For MCP clients, connect to http://127.0.0.1:1024/mcp using Streamable HTTP and the header Authorization: Bearer <service-token>; replace the address and token with those of your service. Discover tools from the connected service rather than assuming a fixed tool catalog. The CLI examples below describe the same operations; use the discovered MCP input schemas when calling tools.

The built-in demo Task can verify submission and tracking without market-data or model credentials; the Alpha158 workflow requires its research plugin and prepared input data. Market-data downloads require AXONX_TUSHARE_TOKEN; model-backed Agents require separate model configuration. See [Quick start](https://flowllm-ai.github.io/AxonX/en/getting-started/quickstart), [Research workflow](https://flowllm-ai.github.io/AxonX/en/research/workflow), and [MCP integration](https://flowllm-ai.github.io/AxonX/en/agent/mcp-integration) for complete setup examples.

When using this document as a skill, perform only the operations required by the user's request. Documentation examples do not authorize installation, task execution, deletion, or remote changes by themselves. For changes to the source checkout, follow its AGENTS.md and [contribution guide](https://github.com/FlowLLM-AI/AxonX/blob/862b90da9c49c3bdee4c2ab9ef896c415aee9f45/CONTRIBUTING.md).

Background

AxonX is a harness framework for financial quantitative research, organizing data acquisition and ETL, factor analysis, model training, prediction, and backtesting into Tasks with consistent input/output contracts.

Plugins register research implementations; Tasks link upstream and downstream work through Task IDs. The CLI and HTTP service support submitting execution on local or remote machines and querying machine resources, runtime status, and logs.

The framework records task configuration, dependencies, result metadata, and artifacts in the workspace, and provides Agents with task, dependency graph, and file query tools to verify research results, investigate failures, and reuse upstream data.

• Authentication: when service authentication is enabled, configure local AXONX_SERVICE_TOKEN or remote AXONX_TARGET_TOKEN in environment variables or .env beforehand.
• Local operations: use the “Command” column without --target. Submit and query Tasks and machine resources directly through the local AxonX HTTP service.
• Discover remote machines: use axonx list_machines to query addresses (address, such as

http://192.168.1.10:1024) and health status (healthy) for all machines configured in the local service's targets, then use axonx machine_status --target <host:port> to inspect candidates'

CPU, memory, and GPU resources.

• Remote operations: once the target address is known, append --target <host:port> from the “Remote arguments” column to commands that support remote operation.

192.168.1.10:1024 in the tables is an example target address; replace it before execution. — means remote operation is unsupported.

Plugin Development

A plugin can register multiple Tasks; the a158 example registers five Task types in plugins/a158/axonx_alpha158/plugin.yaml. The a158

paths, class names, registered names, and dependency chain here are illustrative; replace them with actual definitions when developing other research plugins. Plugin installation and Task submission are separate operations.

Required authoring contracts

Source/API contracts in this guide are bound to the provenance commit, not arbitrary newer releases. Verify the installed CLI help and service version before relying on parameter/response details. Do not infer a successful full dependency/security review from this source citation alone.

Every plugin Task must directly or indirectly inherit BaseTask and follow the public authoring contract in

[axonx/task/core/task.py](https://github.com/FlowLLM-AI/AxonX/blob/862b90da9c49c3bdee4c2ab9ef896c415aee9f45/axonx/task/core/task.py). Registration alone does not replace this contract:

• Declare a fixed task_type, input_cls, output_cls, and a detailed class docstring. Input and output models must

inherit BaseInputParams and BaseOutputParams from [core/params.py](https://github.com/FlowLLM-AI/AxonX/blob/862b90da9c49c3bdee4c2ab9ef896c415aee9f45/axonx/task/core/params.py).

• Implement build_task_steps() to yield synchronous callables in execution order, and build_output_params() to

return a validated instance of the declared output_cls; returning a plain dictionary does not satisfy the contract.

• Preserve framework-managed Task identity, context, lifecycle, and metadata persistence. Use self.task_dir,

source_task_dir(), and resolve_workspace_path() for task artifacts and workspace paths; leave execution and

status recording to the framework runtime.

[axonx/task/contracts/](https://github.com/FlowLLM-AI/AxonX/tree/862b90da9c49c3bdee4c2ab9ef896

… (nội dung đầy đủ có trong gói tải về)