{"id":"da804815-6864-4bd4-ab03-520eb917824a","entityType":"agent","slug":"clawhub-sdk-team-alibabacloud-agentloop-management","name":"alibabacloud-agentloop-management","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sdk-team-alibabacloud-agentloop-management","canonicalPath":"/agent/clawhub-sdk-team-alibabacloud-agentloop-management","generatedAt":"2026-10-11T17:42:29.549Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":null},"description":"The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTask dynamic logging, snapshots, metrics, spans, and JVM inspection.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-agentloop-management","sourceUrl":"https://clawhub.ai/sdk-team/alibabacloud-agentloop-management","homepage":"https://clawhub.ai/sdk-team/skills/alibabacloud-agentloop-management","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sdk-team/alibabacloud-agentloop-management","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sdk-team/skills/alibabacloud-agentloop-management","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"alibabacloud-agentloop-management technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":null},"stars":null,"forks":null,"downloads":1046,"packageName":null,"latestVersion":"0.1.5","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:51:50.739Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T14:51:50.806Z","lastCrawledAt":"2026-10-11T14:51:50.739Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T14:51:50.739Z","lastVerifiedAt":null,"highlights":[{"version":"0.1.5","createdAt":"2026-10-09T06:44:31.619Z","changelog":"- Removed the skill-card.md file. - No other changes to functionality or routing logic.","fileCount":86,"zipByteSize":310935},{"version":"0.1.6","createdAt":"2026-10-09T04:43:58.009Z","changelog":"alibabacloud-agentloop-management v0.1.6 - Major expansion: Added Live-Debug runtime diagnostics and high-code (manual) instrumentation guidance to core capabilities. - New reference docs and scripts for Live-Debug (dynamic logging, snapshots, JVM/runtime/metrics inspection) and high-code AgentLoop instrumentation (loongsuite-genai-utils, OpenTelemetry). - Skill router now dispatches to six domains: onboarding, evaluation, dataset, pipeline, Live-Debug runtime, and high-code instrumentation. - Instrumentation and documentation scripting does not require cloud credentials or browser access. - Enforced stricter multi-domain routing and parameter-completeness protocol, especially for Live-Debug. - Shared conventions and compatibility matrix updated; previous `skill-card.md` removed, new manifest and reference files added.","fileCount":86,"zipByteSize":310805},{"version":"0.1.4","createdAt":"2026-09-01T02:22:40.277Z","changelog":"- Delegated all Experience (ContextStore, recall, API Key) features to the new alibabacloud-agentloop-experience skill; experience support is no longer present in this skill. - Removed experience-related documentation and scripts. - Updated the routing table and dispatch rules to handle only onboarding, evaluation, dataset, and pipeline domains. - Clarified user instructions and error handling for experience requests, directing users to install the separate skill if not available.","fileCount":72,"zipByteSize":258134},{"version":"0.1.3","createdAt":"2026-08-24T02:10:44.308Z","changelog":"- Major documentation and reference update: reorganized and expanded reference files across evaluation, experience, and pipeline topics. - Routing table and domain descriptions clarified for greater accuracy and consistency. - Improved wording for guidance and multi-intent handling; updated descriptions and examples in routing and resource naming contracts. - Removed the obsolete skill-card.md. - Minor formatting polish; updated conventions for clarity and precision.","fileCount":77,"zipByteSize":272091},{"version":"0.1.2","createdAt":"2026-08-18T06:55:10.314Z","changelog":"- Major refactor to a skill router: now routes user requests to one of five AgentLoop domains (onboarding, evaluation, dataset, pipeline, experience). - Separated all operational logic and rules into domain reference files; SKILL.md now only classifies and dispatches. - Expanded support for managing datasets, building pipelines from logs or traces, evaluation workflows, and experience recall. - Improved multi-intent handling and clarified routing logic between overlapping features (dataset, pipeline, evaluation). - Updated unified conventions for session ID, user-agent, command shape, credential security, RAM permissions, and resource naming.","fileCount":77,"zipByteSize":273469},{"version":"0.1.1","createdAt":"2026-07-15T11:08:33.729Z","changelog":"alibabacloud-agentloop-management 0.1.1 - Updated documentation: SKILL.md revised with no logic or interface changes. - Removed obsolete file: skill-card.md deleted. - No runtime or API changes; behavior remains unchanged.","fileCount":7,"zipByteSize":27053},{"version":"0.1.0","createdAt":"2026-07-10T03:10:35.358Z","changelog":"alibabacloud-agentloop-management 0.1.0 initial release: - Enables onboarding of applications into AgentLoop APM/AI monitoring on Alibaba Cloud using the `aliyun cms2` CLI. - Performs prerequisites check: validates aliyun CLI existence, version (>=3.3.15), and cms2 plugin availability. - Enforces workspace naming and selection rules for AgentLoop (must use agentloop-{32-char-code} workspaces). - Requires all CLI calls to include custom User-Agent with a consistent session-id for traceability. - Implements two-phase execution protocol for destructive operations, requiring user confirmation before execution. - Provides detailed guidelines for credential use, error handling, and explicit API invocation for traceability. - Not for general CloudMonitor management or non-AgentLoop use-cases.","fileCount":7,"zipByteSize":27048}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-agentloop-management","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s173swjet2yrebzqrp6hjkvmy583mxef:alibabacloud-agentloop-management` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/sdk-team/alibabacloud-agentloop-management before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T17:42:29.545Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sdk-team-alibabacloud-agentloop-management/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":null},"readme":"Skill: alibabacloud-agentloop-management\n\nOwner: sdk-team\n\nSummary: The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTask dynamic logging, snapshots, metrics, spans, and JVM inspection.\n\nTags: latest:0.1.6\n\nVersion history:\n\nv0.1.5 | 2026-10-09T06:44:31.619Z | auto\n\n- Removed the skill-card.md file.\n- No other changes to functionality or routing logic.\n\nv0.1.6 | 2026-10-09T04:43:58.009Z | auto\n\nalibabacloud-agentloop-management v0.1.6\n\n- Major expansion: Added Live-Debug runtime diagnostics and high-code (manual) instrumentation guidance to core capabilities.\n- New reference docs and scripts for Live-Debug (dynamic logging, snapshots, JVM/runtime/metrics inspection) and high-code AgentLoop instrumentation (loongsuite-genai-utils, OpenTelemetry).\n- Skill router now dispatches to six domains: onboarding, evaluation, dataset, pipeline, Live-Debug runtime, and high-code instrumentation.\n- Instrumentation and documentation scripting does not require cloud credentials or browser access.\n- Enforced stricter multi-domain routing and parameter-completeness protocol, especially for Live-Debug.\n- Shared conventions and compatibility matrix updated; previous `skill-card.md` removed, new manifest and reference files added.\n\nv0.1.4 | 2026-09-01T02:22:40.277Z | auto\n\n- Delegated all Experience (ContextStore, recall, API Key) features to the new alibabacloud-agentloop-experience skill; experience support is no longer present in this skill.\n- Removed experience-related documentation and scripts.\n- Updated the routing table and dispatch rules to handle only onboarding, evaluation, dataset, and pipeline domains.\n- Clarified user instructions and error handling for experience requests, directing users to install the separate skill if not available.\n\nv0.1.3 | 2026-08-24T02:10:44.308Z | auto\n\n- Major documentation and reference update: reorganized and expanded reference files across evaluation, experience, and pipeline topics.\n- Routing table and domain descriptions clarified for greater accuracy and consistency.\n- Improved wording for guidance and multi-intent handling; updated descriptions and examples in routing and resource naming contracts.\n- Removed the obsolete skill-card.md.\n- Minor formatting polish; updated conventions for clarity and precision.\n\nv0.1.2 | 2026-08-18T06:55:10.314Z | auto\n\n- Major refactor to a skill router: now routes user requests to one of five AgentLoop domains (onboarding, evaluation, dataset, pipeline, experience).\n- Separated all operational logic and rules into domain reference files; SKILL.md now only classifies and dispatches.\n- Expanded support for managing datasets, building pipelines from logs or traces, evaluation workflows, and experience recall.\n- Improved multi-intent handling and clarified routing logic between overlapping features (dataset, pipeline, evaluation).\n- Updated unified conventions for session ID, user-agent, command shape, credential security, RAM permissions, and resource naming.\n\nv0.1.1 | 2026-07-15T11:08:33.729Z | auto\n\nalibabacloud-agentloop-management 0.1.1\n\n- Updated documentation: SKILL.md revised with no logic or interface changes.\n- Removed obsolete file: skill-card.md deleted.\n- No runtime or API changes; behavior remains unchanged.\n\nv0.1.0 | 2026-07-10T03:10:35.358Z | auto\n\nalibabacloud-agentloop-management 0.1.0 initial release:\n\n- Enables onboarding of applications into AgentLoop APM/AI monitoring on Alibaba Cloud using the `aliyun cms2` CLI.\n- Performs prerequisites check: validates aliyun CLI existence, version (>=3.3.15), and cms2 plugin availability.\n- Enforces workspace naming and selection rules for AgentLoop (must use agentloop-{32-char-code} workspaces).\n- Requires all CLI calls to include custom User-Agent with a consistent session-id for traceability.\n- Implements two-phase execution protocol for destructive operations, requiring user confirmation before execution.\n- Provides detailed guidelines for credential use, error handling, and explicit API invocation for traceability.\n- Not for general CloudMonitor management or non-AgentLoop use-cases.\n\nArchive index:\n\nArchive v0.1.5: 86 files, 310935 bytes\n\nFiles: references/ai.md (15677b), references/apm.md (47049b), references/dataset/data-operations.md (5438b), references/dataset/dataset-management.md (8048b), references/dataset/dataset.md (17662b), references/dataset/query-syntax.md (6376b), references/dataset/ram-policies.md (3619b), references/dataset/related-commands.md (2445b), references/dataset/verification-method.md (4789b), references/evaluation/acceptance-criteria.md (6462b), references/evaluation/api-map.md (8182b), references/evaluation/cli-installation-guide.md (2153b), references/evaluation/evaluation.md (22736b), references/evaluation/examples/batch-dataset-example.json (838b), references/evaluation/examples/batch-trace-example.json (846b), references/evaluation/examples/oneshot-example.json (694b), references/evaluation/ram-policies.md (3775b), references/evaluation/related-commands.md (3320b), references/evaluation/result-analysis.md (3284b), references/evaluation/spec-format.md (9472b), references/evaluation/verification-method.md (2725b), references/instrumentation/instrumentation.md (14020b), references/instrumentation/sources.md (7807b), references/live-debug-ram-policies.md (5949b), references/live-debug-runtime.md (13604b), references/live-debug.md (41973b), references/manifest.json (19b), references/onboarding.md (11933b), references/pipeline/nodes-and-expressions.md (6054b), references/pipeline/nodes/_TEMPLATE.md (4409b), references/pipeline/nodes/agentic-call.md (9050b), references/pipeline/nodes/dedup-exact.md (6860b), references/pipeline/nodes/dedup-fuzzy.md (6954b), references/pipeline/nodes/dedup-semantic.md (7916b), references/pipeline/nodes/doc-stats.md (5835b), references/pipeline/nodes/embedding.md (5701b), references/pipeline/nodes/extend.md (5030b), references/pipeline/nodes/limit.md (2315b), references/pipeline/nodes/llm-call.md (9240b), references/pipeline/nodes/make-instance.md (22725b), references/pipeline/nodes/OVERVIEW.md (7994b), references/pipeline/nodes/project.md (5044b), references/pipeline/nodes/sample.md (6021b), references/pipeline/nodes/semantic-cluster.md (6576b), references/pipeline/nodes/where.md (4306b), references/pipeline/operators/_TEMPLATE.md (7040b), references/pipeline/operators/agentic-call.md (14634b), references/pipeline/operators/dedup-exact.md (10561b), references/pipeline/operators/dedup-fuzzy.md (12602b), references/pipeline/operators/dedup-semantic.md (13890b), references/pipeline/operators/dedup.md (26673b), references/pipeline/operators/doc-stats.md (7936b), references/pipeline/operators/embedding.md (7615b), references/pipeline/operators/extend.md (4702b), references/pipeline/operators/limit.md (2632b), references/pipeline/operators/llm-call.md (21165b), references/pipeline/operators/make-instance.md (31234b), references/pipeline/operators/OVERVIEW.md (7946b), references/pipeline/operators/project.md (4429b), references/pipeline/operators/sample.md (10556b), references/pipeline/operators/semantic-cluster.md (9519b), references/pipeline/operators/where.md (3779b), references/pipeline/pipeline-cli-map.md (8628b), references/pipeline/pipeline.md (27116b), references/pipeline/ram-policies.md (6044b), references/pipeline/related-commands.md (6384b), references/pipeline/spec-format.md (8479b), references/pipeline/trace/ot-ai-collection-spec.md (39256b), references/pipeline/trace/ot-ai-trace-recipe.md (7427b), references/pipeline/verification-method.md (8535b), references/ram-policies.md (5747b), scripts/evaluation/agentloop_eval.py (51286b), scripts/evaluation/analyze_evaluation_results.py (18496b), scripts/evaluation/requirements.txt (465b), scripts/instrumentation/fetch_docs.py (28806b), scripts/live-debug/common.sh (4937b), scripts/live-debug/delete_all_probes.sh (2514b), scripts/live-debug/delete_task.sh (1422b), scripts/live-debug/get_task.sh (995b), scripts/live-debug/list_tasks.sh (1413b)\n\nFile v0.1.5:SKILL.md\n\n---\nname: alibabacloud-agentloop-management\ndescription: |\n  The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTask dynamic logging, snapshots, metrics, spans, and JVM inspection.\nlicense: Apache-2.0\nmetadata:\n  domain: aiops\n  owner: agentloop\n  contact: agentloop@alibaba-inc.com\n---\n\n# AgentLoop Skill Router\n\n> **Positioning**: This skill is the single entry point for Alibaba Cloud **AgentLoop** requests. It only classifies the user's intent and dispatches to one of the six domain playbooks below. All executable rules - prerequisites, credentials, RAM policies, parameter confirmation, safety protocols, command usage, and verification - live inside the domain files. Do not run any cloud operation before reading the matched domain file.\n\n**Compatibility**: cloud-operation domains require Aliyun CLI 3.3.15 or later; Pipeline requires `aliyun-cli-agentloop` 0.7.4 or later; bundled evaluation, Pipeline, and public-document retrieval scripts require Python 3.8 or later. Instrumentation guidance and public-document retrieval do not require Aliyun CLI, cloud credentials, or a browser.\n\n## Routing Table\n\n| # | Domain | Intent | Entry file (read first) |\n|---|--------|--------|-------------------------|\n| 1 | Application onboarding (APM & AI observability) | Instrument an application so it reports to AgentLoop: probe or agent install, APM onboarding, `aliyun-bootstrap`, `AliyunJavaAgent`, `instgo`, `cms_node_sdk`, `ack-onepilot`, OpenTelemetry, LicenseKey, K8s/ACK/ECS onboarding, LLM and AI-framework tracing (Dify, LangChain, DashScope) | [references/onboarding.md](references/onboarding.md) - internally routes to [references/apm.md](references/apm.md) / [references/ai.md](references/ai.md) |\n| 2 | Evaluation | Score model, agent, or trace quality: create and update evaluators and evaluator skills, one-shot sample tests, batch trace or Dataset evaluation, trace backfill, poll an evaluation task, analyze results and low-score cases | [references/evaluation/evaluation.md](references/evaluation/evaluation.md) |\n| 3 | Dataset | Store and retrieve structured rows: Dataset lifecycle and schema, append rows with `add-dataset-data`, read-only queries with `execute-query`, SQL or SearchExpr, semantic search, embedding fields | [references/dataset/dataset.md](references/dataset/dataset.md) |\n| 4 | Pipeline | Transform source data into a Dataset once or on a schedule: import Logstore/SLS data into a Dataset, import traces, design specs, preview/create/run, inspect runs, control the lifecycle, configure processing nodes, and map OT AI traces | [references/pipeline/pipeline.md](references/pipeline/pipeline.md) |\n| 5 | Live-Debug runtime diagnostics | Diagnose an already-running Java or Python application with CMS ServiceTask: dynamic log/snapshot/metric/span probes, JVM commands (OGNL, decompile, thread/memory/runtime inspection), disable/clear probes, and query capture results through SLS | [references/live-debug-runtime.md](references/live-debug-runtime.md) |\n| 6 | High-code instrumentation | Teach, implement, or troubleshoot manual instrumentation for AgentLoop with loongsuite-genai-utils / language-specific GenAI Utils and OpenTelemetry SDK: Java, Go, Python, Node.js; LLM/Agent/Tool/Retrieval spans, LLM Trace field formats, async/cross-process context propagation, business attributes and broken traces | [references/instrumentation/instrumentation.md](references/instrumentation/instrumentation.md) — dynamically retrieves official documentation without a browser |\n\n## Dispatch Rules\n\n1. Classify the request into one or more domains using the routing table, then read **only** the matched domain entry file(s). Never preload all domains.\n   For high-code/manual instrumentation, GenAI field semantics, or context propagation, dispatch to **High-code instrumentation first**. Only add Application onboarding when cloud setup, endpoint discovery, or service registration is actually needed; code guidance must not be blocked by onboarding's CLI/workspace prerequisites.\n2. Follow the matched domain file completely. Each domain defines its own prerequisites, credentials check, RAM policies, parameter confirmation, execution-safety protocol, and verification method.\n   For Live-Debug, the migrated entry file preserves the original skill contract and is authoritative for that domain wherever its module-specific rules differ from the shared conventions below.\n   For a vague Live-Debug request, apply its parameter-completeness gate immediately after reading the entry file: state which target information is missing and stop. Treat the clarification as a completed final response for this run, not a request for another message. Use only declarative wording such as `Required inputs for a future run: ...`. The response MUST NOT contain a question mark or any request/invitation phrase, including `please provide`, `provide`, `send`, `reply`, `tell me`, `can you`, `could you`, `请提供`, `请补充`, `提供`, `补充`, `告知`, or `回复`. End exactly with `No diagnostic or cloud action was executed; this run is complete.` Do not run prerequisite checks, discover workspaces/services, inspect credentials, create output files, or issue any cloud call until a future request already supplies the required information.\n3. If the request matches none of the domains, state that it is out of scope for this skill and do not dispatch.\n4. If the intent is ambiguous between two domains, ask one clarifying question before dispatching.\n\n### Disambiguating Dataset vs Pipeline vs Evaluation\n\n- Writing or reading rows the user already has: **Dataset**.\n- Deriving new rows from LogStore or trace data through processing nodes: **Pipeline**. Create or confirm the sink Dataset first.\n- Judging the quality of existing traces or Dataset rows with an evaluator: **Evaluation**.\n\n## Delegated Domain: Experience\n\nExperience work - recalling prior experience, similar cases, past incidents and fixes, old runbooks, lessons learned, and the lifecycle of experience stores (ContextStore) and their API Keys - is **not** implemented in this skill. It lives in the separate `alibabacloud-agentloop-experience` skill.\n\nWhen a request needs experience, on its own or as one step of a multi-domain request:\n\n1. Check whether the `alibabacloud-agentloop-experience` skill is available in the current environment.\n2. If it is available, hand the experience part off to it and follow that skill's own rules. Do not reimplement recall or ContextStore commands here.\n3. If it is not available, tell the user that this part requires the separate skill and point them at <https://skills.aliyun.com/skills/alibabacloud-agentloop-experience> to install it. Offer to help with the installation, and wait for the user's answer.\n4. Never guess at experience behavior in place of the missing skill. Continue with the remaining in-scope domains and report the experience step as blocked on that skill.\n\n## Multi-Intent Handling\n\n- Execute multiple domains sequentially in dependency order; finish and verify one mutation stage before starting the next.\n- For Logstore-to-Dataset materialization: confirm or create the Dataset schema, preview the Pipeline, create and observe the Pipeline run, then read back and reconcile Dataset contents. Start Evaluation only after the Dataset field contract passes.\n- When the user also asks to reuse prior work, resolve that experience step through the delegated skill above before the in-scope domains start, and say so if the skill is missing.\n\n## Shared Conventions\n\n- **Skill version gate (before the first cloud call)**: read and parse [references/manifest.json](references/manifest.json), require a non-empty string `version`, and keep that exact value for the workflow. If the file is missing, invalid JSON, or has no valid `version`, stop before issuing any Alibaba Cloud API call and report the manifest error. Do not guess, hard-code, or fall back to another version.\n- **Session ID**: generate one 32-character lowercase hex session ID once at the start of the workflow (`openssl rand -hex 16`) and reuse that same value for the rest of the session. Keep the generated value and write it out literally in every command that needs it. Do not re-derive it per command, and do not reach for it through a shell variable or a `cat` of a saved file - either one forces an assignment in front of the call and breaks the command shape rule below.\n- **User-Agent**: every `aliyun` CLI cloud API command must carry `--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/skill-version/{version}/{session-id}\"`, using the manifest-derived version and the workflow session ID. Bundled wrappers enforce the same manifest gate and format. Local `configure`, `plugin`, and `version` commands are excluded because they are not cloud API calls.\n- **Command shape**: every cloud API call must run as a single-line bare command whose first token is `aliyun`, or `python3` for a bundled wrapper, and whose last token is the final flag of that same call. Nothing may come before it - no `VAR=value` assignment, no `set -o pipefail`, no `source`, no `cd`, no `bash some_script.sh` wrapper - and a newline between an assignment and the call still counts as coming before it. Nothing may come after it either - no `| tee`, no `| head`, no `2>&1`, no `> file` redirect, and no `&&` or `;` chaining onto a second command. Diagnostic probes such as `--help` follow the same rule. When the environment asks for a log of executed actions, run the bare call first and then write the command text and its output into the log as a separate file-write step; a single action log listing each command and its result satisfies that requirement in full, so piping a call into `tee` adds nothing and only corrupts the record of what ran. The command that executes must be the API call itself and nothing else, so that run records, audit trails, and CLI tooling all see it verbatim.\n- **Credential red lines**: never read, echo, or print AK/SK/STS-token values or the APM LicenseKey (`entryPointInfo.authToken`) - in chat answers, summaries, credential tables, generated snippets, or report files. Keep every retrieved credential inside an environment variable, report only whether it was obtained, and reference the variable name instead of the value. Never ask the user to paste literal credentials; never run `aliyun configure set` with literal credential values; use only `aliyun configure list` to check identity status. Onboarding redaction recipe: [references/onboarding.md](references/onboarding.md#credential-output-redaction).\n- **RAM permissions**: use [references/ram-policies.md](references/ram-policies.md) as the skill-wide index. Never put `*` in an Action list. Grant destructive actions separately and deliberately.\n- **Resource names**: confirm each resource's exact naming contract before create; Dataset and Pipeline use different character sets.\n\n| Resource | Flag | Pattern | Hyphen | Underscore |\n|---|---|---|---|---|\n| Pipeline | `--pipeline-name` | `^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$` | Separator | Rejected |\n| Dataset | `--dataset-name` | `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, 4-63 chars | Rejected | Separator |\n\nFile v0.1.5:_meta.json\n\n{\n  \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n  \"slug\": \"alibabacloud-agentloop-management\",\n  \"version\": \"0.1.5\",\n  \"publishedAt\": 1791528271619\n}\n\nFile v0.1.5:references/ai.md\n\n# AI Observability Module\n\n> Global conventions (credentials, Observability / User-Agent, output format, error codes, command prefix) - see [onboarding.md](onboarding.md).\n> RAM permissions - see [ram-policies.md](ram-policies.md).\n> Run `aliyun cms2 apm <subcommand> --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard AI applications (LLM-based services, AI Agents, custom instrumented apps) into AgentLoop application observability. Uses `aliyun cms2` CLI to initialize APM infrastructure, retrieve access credentials, and generate framework-specific configuration.\n\nFor high-code instrumentation with GenAI Utils / OpenTelemetry SDK, field-format questions, or broken async/cross-process traces, use [instrumentation/instrumentation.md](instrumentation/instrumentation.md) before this cloud workflow. That module dynamically retrieves the language guides, field specification, and all relevant best-practice candidates without requiring a browser or cloud credentials. Return here only when cloud setup is needed.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported AI frameworks.\n\n**Out-of-Scope**: Model fine-tuning or training observability; GPU monitoring (see `cloud-acs-ecs-gpu` addon); general CloudMonitor (CMS) management; `default-cms-*` or other non-`agentloop-*` workspaces; alerts, RUM, Prometheus rules, and other non-onboarding CMS features.\n\n---\n\n## Workspace Mandatory Rules\n\n> **CRITICAL** - AgentLoop AI onboarding requires an explicit AgentLoop workspace from the user.\n\n1. **Always ask user to provide `workspace`**: Never auto-build workspace as `default-cms-{AccountId}-{regionId}`.\n2. **Workspace format is `agentloop-{32-char-code}`**: If missing, run `aliyun cms2 workspace list -o json` and reuse the first `agentloop-[0-9a-f]{32}` match. On quota 403/400, reuse existing `agentloop-*` workspace and continue.\n3. **Do NOT proceed without a valid workspace**: All APM commands require the user-provided or discovered `agentloop-*` workspace.\n\n---\n\n## Execution Safety Protocol\n\nFollow the same Two-Phase Execution Protocol as [apm.md - Execution Safety Protocol](apm.md#execution-safety-protocol).\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`\n- AgentLoop platform resource creation: `apm configuration create`, `apm service create`\n- Retrieving credentials: `apm configuration get` (the returned LicenseKey must stay redacted - see [onboarding.md - Credential Output Redaction](onboarding.md#credential-output-redaction))\n- Fetching addon templates: `integration addon get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Deleting service records: `apm service delete`\n- Modifying user application startup scripts or Dockerfiles\n\n---\n\n## Supported Frameworks\n\n| Framework | Addon Name | Protocols | Underlying Agent |\n|-----------|-----------|-----------|-----------------|\n| **Dify** | `ai-dify` | opentelemetry | Dify console built-in OTel configuration |\n| **LangChain/LangGraph** | `ai-langchain-langgraph` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **DashScope** | `ai-dashscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **AgentScope** | `ai-agentscope` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **OpenAI** | `ai-openai` | arms, arms4cs, opentelemetry | Python aliyun-bootstrap |\n| **Coze** | `ai-coze` | arms-ecs, arms-ack, opentelemetry | Golang (arms-ecs: instgo, arms-ack: ack-onepilot) |\n| **OpenClaw** | `ai-openclaw` | opentelemetry | dedicated installer script |\n| **CoPaw** | `ai-copaw` | opentelemetry | dedicated installer script |\n| **Hermes** | `ai-hermes` | opentelemetry | dedicated installer script |\n| **custom instrumentation** | `ai-custom-instrumentation` | agent-extension, manual | ARMS agent extension / manual OTel SDK |\n\n**Protocol legend**:\n- `arms` - proprietary Python agent (general environment), serviceType = `TRACE`\n- `arms4cs` - proprietary Python agent (container environment), serviceType = `TRACE`\n- `arms-ecs` / `arms-ack` - proprietary agent (by deployment environment), serviceType = `TRACE`\n- `opentelemetry` - OpenTelemetry protocol, serviceType = `XTRACE`\n- `agent-extension` / `manual` - custom instrumentation, serviceType = `TRACE`\n\n---\n\n## CLI Commands Reference\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `apm configuration create` | Initialize APM infrastructure (idempotent) | `--workspace`, `--region` |\n| `apm configuration get` | Get LicenseKey, Endpoint, project | `--workspace`, `--region` |\n| `apm service create` | Register application service | `--workspace`, `--region`, `--body` |\n| `apm service list` | List/filter registered services | `--workspace`, `--region`, `--service-name` |\n| `apm service delete` | Delete a service record | `--workspace`, `--region`, `--service-id` |\n| `integration addon get` | Fetch addon template + schema | `--addon-name`, `--env-type Client` |\n\n---\n\n## Onboarding Workflow\n\n### Step 1 - Gather Parameters\n\nCollect from user:\n\n| Parameter | How to obtain |\n|-----------|---------------|\n| `workspace` | **Ask user explicitly**, or discover via `aliyun cms2 workspace list` (first `agentloop-[0-9a-f]{32}` match). On quota 403/400, reuse existing `agentloop-*` workspace. Format: `agentloop-{32-char-code}`. Do NOT auto-derive. |\n| `regionId` | Ask user (e.g., `cn-hangzhou`, `ap-southeast-1`), or derive from cluster metadata / kubeconfig context when applicable |\n| `appName` | Ask user - the application/service name |\n| `framework` | Ask user - which AI framework (Dify, LangChain, etc.) |\n| `network` | Ask user - `public` or `VPC` (not needed for Dify console config) |\n| `protocol` | Present available protocols from [Supported Frameworks](#supported-frameworks) and ask user to choose |\n\n### Step 2 - Initialize APM Infrastructure\n\n```bash\naliyun sts get-caller-identity --force -o json\n\n# Use user-provided workspace (format: agentloop-{32-char-code})\n# workspace={userProvidedWorkspace}\n\n# Initialize (idempotent)\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}\n```\n\n### Step 3 - Get Credentials\n\n```bash\n# LicenseKey goes straight into an env var - never onto a printed line\nexport ARMS_LICENSE_KEY=\"$(aliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json | jq -r '.data.entryPointInfo.authToken')\"\n\n# Non-sensitive fields for the report\naliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json \\\n | jq '{status: .data.status,\n licenseKeyObtained: (.data.entryPointInfo.authToken | length > 0),\n publicDomain: .data.entryPointInfo.publicDomain,\n privateDomain: .data.entryPointInfo.privateDomain,\n project: .data.entryPointInfo.project}'\n```\n\nExtract from response:\n- `entryPointInfo.authToken` -> `$ARMS_LICENSE_KEY` (**never printed** - report only whether it was obtained)\n- `entryPointInfo.publicDomain` -> `{publicEndpoint}`\n- `entryPointInfo.privateDomain` -> `{vpcEndpoint}`\n- `entryPointInfo.project` -> `{project}`\n\n> **Mandatory**: every artifact produced afterwards - probe configuration snippets, credential summaries, execution reports, and files written under `outputs/` - references `$ARMS_LICENSE_KEY` instead of the token value, and never dumps the raw `apm configuration get` JSON. Full rules: [onboarding.md - Credential Output Redaction](onboarding.md#credential-output-redaction).\n\n### Step 4 - Register Application Service\n\n```bash\naliyun cms2 apm service create --workspace {workspace} --region {regionId} \\\n --body '{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"{serviceType}\",\n \"attributes\": [\n {\"key\": \"language\", \"value\": \"{language}\"}\n ]\n }'\n```\n\n**serviceType mapping**: see [Protocol legend](#supported-frameworks).\n\n**language attribute**: based on the framework's underlying agent (e.g., `python` for LangChain/LangGraph/DashScope/AgentScope/OpenAI); refer to addon template for framework-specific values; omit if unknown.\n\n### Step 5 - Generate Configuration\n\nRoute to the appropriate path based on user's selected `protocol` and `framework`.\n\n#### Path A - Reuse apm.md Existing Flows (proprietary agent)\n\nFor protocols that correspond to existing apm.md onboarding flows, do NOT call `integration addon get`. Instead, follow the linked apm.md section directly with Step 3 credentials.\n\n| Protocol | Framework | Follow |\n|----------|-----------|--------|\n| `arms` | LangChain/LangGraph, DashScope, AgentScope, OpenAI | [apm.md - Python - Aliyun Agent (aliyun-bootstrap)](apm.md#python--aliyun-agent-aliyun-bootstrap) |\n| `arms4cs` | LangChain/LangGraph, DashScope, AgentScope, OpenAI | [apm.md - Python - ack-onepilot (K8s)](apm.md#python--ack-onepilot-k8s) |\n| `arms-ecs` | Coze | [apm.md - Golang - instgo compile (ECS / Host)](apm.md#golang--instgo-compile-ecs--host) |\n| `arms-ack` | Coze | [apm.md - Golang - ack-onepilot (K8s)](apm.md#golang--ack-onepilot-k8s) |\n\n#### Path B - Addon Dynamic Fetch\n\nFor all other protocols (`opentelemetry`, `agent-extension`, `manual`), and for frameworks without proprietary agent support (Dify, OpenClaw, CoPaw, Hermes), use `integration addon get` to fetch the configuration template at runtime.\n\n1. Fetch addon card:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json\n```\n\n2. Extract the target protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocol}\") | .codeTemplate'\n```\n\n3. Render variables with Step 3 credentials:\n\n| Template Variable | Value Source |\n|-------------------|--------------|\n| `{{region}}` | `{regionId}` |\n| `{{LicenseKey}}` | `entryPointInfo.authToken` - render as `$ARMS_LICENSE_KEY`, never as the literal token |\n| `{{workspace}}` / `{{$context$.workspace}}` | `{workspace}` |\n| `{{Project}}` | `entryPointInfo.project` |\n| `{{PubDomain}}` / `{{PubAddr}}` | `entryPointInfo.publicDomain` |\n| `{{VpcDomain}}` / `{{InnerAddr}}` | `entryPointInfo.privateDomain` |\n| `{{serviceName}}` | `{appName}` |\n| `{{version}}` | Ask user (default: `1.0.0`) |\n| `{{environment}}` | Ask user (default: `production`) |\n| `{{connectionType}}` | `inner` (VPC) or `public` |\n| `{{exportMethod}}` | Must be selected from `schema.props.dataSource` |\n\n4. **Interactive parameter confirmation rules**:\n - For branch/select parameters (`connectionType`, `exportMethod`, `instrumentType`, `source`), ask the user to choose explicitly with concrete options from schema `dataSource`. Do NOT auto-select or silently use defaults.\n - For `{{version}}` and `{{environment}}`, always ask user to confirm with suggested defaults.\n - If schema and template disagree on allowed values, **schema wins**.\n - Only ask for parameters that are actually referenced by the selected template branch.\n\n5. Present rendered steps to user, with the LicenseKey still expressed as `$ARMS_LICENSE_KEY`.\n\n### Step 6 - Post-Onboarding Verification\n\n```bash\naliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json\n```\n\n**Expected**: service appears with correct `serviceType` and `serviceName`. After restarting the application with the generated configuration, data should appear in AgentLoop console within 2-3 minutes.\n\n---\n\n## Framework-Specific Notes\n\n### Dify\n\n- Dify >= 1.6.0 has built-in OTel tracing. Configure LicenseKey and Endpoint in Dify console > Monitoring > Trace application performance > AgentLoop. No agent installation is required.\n- The Dify console needs a human to paste the LicenseKey: tell the user which field to fill and where to copy the value from (`apm configuration get` output in their own shell, or the AgentLoop console) - never echo the value for them.\n- Only the `opentelemetry` protocol is supported. Fetch configuration parameters from the addon template and enter them in the Dify console.\n- No `aliyun-instrument` or other agent installation step is required.\n\n### Coze\n\n- Underlying runtime is Golang. Protocol names differ from other frameworks: `arms-ecs` / `arms-ack` (not `arms`/`arms4cs`).\n- `arms-ecs` -> Reuse [apm.md Golang - instgo](apm.md#golang--instgo-compile-ecs--host)\n- `arms-ack` -> Reuse [apm.md Golang - ack-onepilot](apm.md#golang--ack-onepilot-k8s)\n- `opentelemetry` -> Fetch Go OTel Agent configuration from the addon template.\n\n### OpenClaw / CoPaw / Hermes\n\n- Each framework provides a dedicated installer script (`curl -fsSL ... | bash`) that installs the corresponding observability plugin.\n- Pass parameters via `--x-arms-license-key \"$ARMS_LICENSE_KEY\"`, `--serviceName`, and `--endpoint`; keep the token in the environment variable rather than inlining it in the installer command.\n- Only the `opentelemetry` protocol is supported. Render output from the addon template.\n\n### LangChain/LangGraph / DashScope / AgentScope / OpenAI\n\n- `arms` / `arms4cs` protocols -> Reuse [apm.md Python - Aliyun Agent](apm.md#python--aliyun-agent-aliyun-bootstrap); auto-instruments LLM calls, tool use, and agent traces.\n- `opentelemetry` protocol -> Fetch OTel SDK configuration from the addon template.\n\n### custom instrumentation\n\n- Read [instrumentation/instrumentation.md](instrumentation/instrumentation.md) for language-specific dependencies, APIs, field formats, and context propagation; `loongsuite-genai-utils` is a capability name, not a universal package/import name.\n- `agent-extension`: Reuse the supported agent's provider and context integration according to the matching language and agent version. Do not initialize a second exporter/provider merely to add spans.\n- `manual`: Configure the standard OpenTelemetry SDK and exporter when the application does not already have a provider.\n- Addon templates supply platform configuration when cloud onboarding is needed. They do not replace the current language guide, LLM Trace field specification, or related best-practice documents.\n\n---\n\n## Offboarding / Uninstall\n\nOffboarding is the reverse of onboarding: **remove agent configuration from the application first, then clean up AgentLoop platform resources**.\n\n| Step | Action | Command / Procedure |\n|------|--------|---------------------|\n| 1 | Remove agent from application | Reverse of Step 5: remove the agent wrapper, environment variables, disable tracing in the Dify console, or uninstall the plugin script (framework-specific) |\n| 2 | Restart application | Restart without agent params |\n| 3 | Verify agent stopped | Confirm no new data appears in AgentLoop console after 3-5 minutes |\n| 4 | Delete service record (**requires user confirmation**) | `aliyun cms2 apm service delete --workspace {workspace} --service-id {serviceId} --region {regionId}` |\n\n---\n\n## Error Handling & Fallback\n\n| Error | Cause | Resolution |\n|-------|-------|------------|\n| `addon not found` | Addon name incorrect or not yet available in region | Verify addon name from [Supported Frameworks](#supported-frameworks); for Python-based frameworks fallback to [apm.md Python section](apm.md#python--aliyun-agent-aliyun-bootstrap) |\n| `workspace not found` | APM infrastructure not initialized | Run `apm configuration create` first (Step 2) |\n| `service already exists` | Duplicate serviceName | Use `apm service list` to check, then update or delete existing service |\n| `InvalidJSON` | Malformed `--body` | Validate with `jq . <<<'<value>'` before passing to CLI |\n| Template variable unresolved | `{{var}}` in rendered output | Check variable mapping table in Step 5; ensure all credentials from Step 3 are substituted |\n\nFile v0.1.5:references/apm.md\n\n# Application Monitoring (APM) Module\n\n> Global conventions (credentials, Observability / User-Agent, output format, error codes, command prefix) - see [onboarding.md](onboarding.md).\n> RAM permissions - see [ram-policies.md](ram-policies.md).\n> Run `aliyun cms2 apm <subcommand> --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard server-side applications into AgentLoop application observability. Uses `aliyun cms2` CLI to initialize APM infrastructure and retrieve access credentials, then generates configuration for the user's specific language and deployment method.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported languages, **auto-modify K8s Deployment YAML** (with user confirmation) via `aliyun cs` + `kubectl`.\n\n**Out-of-Scope (this version)**: Automatic modification of ECS host startup scripts / Dockerfile; agent binary downloads; general CloudMonitor (CMS) management; `default-cms-*` or other non-`agentloop-*` workspaces; alerts, RUM, Prometheus rules, and other non-onboarding CMS features.\n\n---\n\n## Workspace Mandatory Rules\n\n> **CRITICAL** - AgentLoop onboarding requires an explicit AgentLoop workspace from the user. The following rules are **absolute and non-negotiable**.\n\n1. **Always ask user to provide `workspace`**: Never auto-build workspace as `default-cms-{userId}-{regionId}` or any other derived format.\n2. **Workspace format is `agentloop-{32-char-code}`**: Prefix `agentloop-` followed by exactly 32 characters (e.g. `agentloop-2694ecf8****************1f84542d`). If missing or invalid, run `aliyun cms2 workspace list -o json` and reuse the first matching `agentloop-[0-9a-f]{32}` workspace; if none match, stop and prompt: **Please provide a valid AgentLoop workspace in the format `agentloop-{32-char-code}`.**\n3. **Quota fallback**: if workspace creation hits **403/400** quota errors, list existing workspaces, reuse a matching `agentloop-*` workspace, log the reuse reason, and continue - do not abort or fall back to `default-cms-*`.\n4. **Do NOT proceed without a valid workspace**: All `apm configuration` / `apm service` commands require `--workspace`; do not guess or fabricate a value.\n5. **Region must be obtained separately**: `regionId` is NOT encoded in the workspace name. Derive it from cluster metadata or kubeconfig context in container flows; ask the user in non-container flows.\n\n---\n\n## Container Onboarding Mandatory Rules\n\n> **CRITICAL** - When the user selects container (ACK/ACS/K8s) onboarding, the following rules are **absolute and non-negotiable**. Violating any of them is a workflow error.\n\n1. **Do NOT ask user for `regionId`**: In container onboarding, `regionId` must be derived automatically from cluster metadata or kubeconfig context. Never prompt the user for region. If derivation fails, use `aliyun cs describe-clusters` output to extract `region_id` from cluster info.\n2. **Do NOT run any `integration addon list` or `integration addon get` commands**: Container onboarding uses ack-onepilot component check + workload label patching. Addon discovery is exclusively for non-container (ECS/host) OpenTelemetry scenarios.\n3. **Do NOT mention \"Addon\" to the user**: When asking the user to select onboarding type, use the prompt \"Please select the onboarding type?\" (not \"Please select the onboarding protocol type? (Addon type)\" or any variant containing \"Addon\").\n4. **Do NOT ask user for `network` type**: Container onboarding uses ack-onepilot label injection - there is no agent download URL or endpoint configuration, so public/VPC distinction is irrelevant. Skip the network question entirely.\n\n**Trigger recognition**: User mentions any of the following -> treat as container onboarding: K8s, ACK, ACS, container, container service, Kubernetes, cluster.\n\n**Container onboarding flow summary** (no addon, no regionId prompt, no network prompt):\n1. Determine it's container onboarding (user says ACK/ACS/K8s)\n2. Ask user for: `workspace` (format: `agentloop-{32-char-code}`), `appName`, `language`; collect `clusterId` (from user input or derive from context)\n3. Derive `regionId` from cluster info or kubeconfig context (NOT from workspace name; NOT by asking user in container flow); skip `network` (irrelevant for ack-onepilot)\n4. Validate `workspace` matches `agentloop-{32-char-code}`; if not, stop and ask user to provide a valid AgentLoop workspace\n5. Check ack-onepilot component -> Install if missing (with Two-Phase confirmation)\n6. Patch Deployment with labels (with Two-Phase confirmation)\n\n> **Language limitation**: Node.js and PHP do NOT support ack-onepilot. For these languages on K8s, guide the user to use OpenTelemetry env vars or manual SDK startup instead of ack-onepilot labels.\n\n---\n\n## Execution Safety Protocol\n\n**Two-Phase Execution Protocol** - applies to operations that **modify the user's application or cluster** (e.g., patching Deployments, installing components, modifying startup scripts):\n\n1. **Phase A (Plan)**: Present the complete execution plan including exact commands, target resources, and expected impact. End your turn immediately after presenting the plan.\n2. **Phase B (Execute)**: Only proceed after the user's NEXT message contains explicit approval (\"yes\", \"confirm\", \"proceed\", \"go ahead\").\n\n**Mandatory Rules**:\n- Do NOT combine Phase A and Phase B in the same response.\n- Do NOT interpret silence or unrelated messages as approval.\n- If user says \"no\", \"cancel\", or asks to modify -> return to Phase A with adjustments.\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`, `describe`, `describe-clusters`\n- AgentLoop platform resource creation: `apm configuration create`, `apm service create` (these are AgentLoop platform infrastructure, not user application changes)\n- Retrieving credentials: `apm configuration get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Installing cluster components: `install-cluster-addons` (ack-onepilot)\n- Patching K8s Deployments: `kubectl patch deployment`\n- Modifying user application startup scripts or Dockerfiles\n- Any `kubectl apply` / `kubectl delete` on user workloads\n- Deleting service records: `apm service delete` (destructive - removes historical monitoring data association)\n\n> **Always offer manual alternative**: When presenting Phase A, also mention the manual way to achieve the same result (console URL, kubectl edit, manual file editing). Let the user choose between automated execution and self-service.\n\n**Plan output format** (use Markdown list, avoid box-drawing characters):\n```markdown\n### Execution Plan\n\n- Target: [what will be changed]\n- Commands:\n - `command 1`\n - `command 2`\n- Impact: [blast radius / what gets created or modified]\n- Rollback: [yes/no, how]\n\nPlease confirm execution (`yes` / `no`).\n```\n\n---\n\n## Supported Languages and Methods\n\n| Language / Component | proprietary agent | ack-onepilot (K8s) | OpenTelemetry | eBPF |\n|----------|:-:|:-:|:-:|:-:|\n| **Java** | AliyunJavaAgent | Yes | OTel Java Agent | - |\n| **Golang** | instgo compile | Yes | OTel Go Agent / SDK | - |\n| **Python** | aliyun-bootstrap | Yes | opentelemetry-instrument | - |\n| **Node.js** | @loongsuite/cms_node_sdk | - | OTel Node SDK | - |\n| **PHP** | - | - | OTel PHP extension | - |\n| **.NET** | - | - | OTel .NET Auto-Instrument | OBI (DaemonSet) |\n| **Nginx** | - | - | ngx_otel_module | - |\n| **Kong** | - | - | Kong OTel Plugin | - |\n| **APISIX** | - | - | APISIX OTel Plugin | - |\n\n---\n\n## CLI Commands Reference\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `apm configuration create` | Initialize APM backend infrastructure | `--workspace`, `--region` |\n| `apm configuration get` | Retrieve authToken, endpoints, project | `--workspace`, `--region` |\n| `apm service create` | Register application service | `--workspace`, `--body` (JSON or @file) |\n| `apm service list` | List/verify existing services | `--workspace`, `--service-name`, `--service-type` |\n| `apm service get` | Get service details | `--workspace`, `--service-id` |\n| `apm service delete` | Remove a service | `--workspace`, `--service-id` |\n\n> **Important**: `apm service create --body` requires `< /dev/null` when piping in some shell environments to avoid stdin conflicts.\n\n---\n\n## Onboarding Workflow (6 Steps)\n\n### Step 1 - Gather Parameters\n\n| Parameter | Required | How to Obtain |\n|-----------|----------|---------------|\n| `regionId` | Conditional | **Container onboarding:** Automatically derive from clusterId via `aliyun cs describe-clusters` response (`region_id` field), NEVER ask user. **Non-container onboarding:** Always ask user to confirm. |\n| `userId` (AccountId) | Yes | `aliyun sts get-caller-identity` -> `.AccountId`, or ask user |\n| `workspace` | Yes | **User must provide explicitly**, or discover via `aliyun cms2 workspace list` (first `agentloop-[0-9a-f]{32}` match). Format: `agentloop-{32-char-code}`. On quota 403/400, reuse existing `agentloop-*` workspace and continue. Do NOT auto-derive `default-cms-{userId}-{regionId}`. |\n| `appName` | Yes | Always ask user to confirm application name |\n| `language` | Yes | java / golang / python / nodejs / php / dotnet |\n| `method` | Yes | proprietary agent / otel / ack-onepilot (prompt: \"Please select the onboarding type?\") |\n| `network` | Conditional | **Container onboarding:** Do NOT ask - ack-onepilot handles connectivity internally, network type is irrelevant. **Non-container onboarding:** Always ask user (public or VPC, affects download URL and endpoint). |\n\n### Step 2 - Initialize APM Infrastructure\n\n```bash\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}\n```\n\nIdempotent - if already initialized, returns successfully. Use `apm configuration get` to check status.\n\n### Step 3 - Retrieve Access Credentials\n\n```bash\naliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json\n```\n\n**Example real response** (status=Running means ready):\n```json\n{\n \"success\": true,\n \"data\": {\n \"entryPointInfo\": {\n \"authToken\": \"<LicenseKey - never echo this value, see Credential Handling below>\",\n \"privateDomain\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou.cn-hangzhou-intranet.log.aliyuncs.com\",\n \"project\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou\",\n \"publicDomain\": \"proj-xtrace-d1265ec453407aba9ef476c91f84542d-cn-hangzhou.cn-hangzhou.log.aliyuncs.com\"\n },\n \"feeType\": \"arms=serverless;xtrace=serverless\",\n \"regionId\": \"cn-hangzhou\",\n \"requestId\": \"D9A655EE-3A76-5B16-88AA-60BE3B4D7A03\",\n \"settings\": {\n \"arms_switch\": \"enable\",\n \"trace_aggregate\": \"enable\",\n \"xtrace_switch\": \"enable\"\n },\n \"status\": \"Running\",\n \"type\": \"apm\",\n \"workspace\": \"agentloop-2694ecf8****************1f84542d\"\n }\n}\n```\n\nThe `status` field indicates the observability instance lifecycle state:\n\n| Status | Meaning | Action |\n|--------|---------|--------|\n| `Created` | Provisioning in progress; resources are initializing asynchronously | Proceed to next step |\n| `Running` | Fully operational | Proceed to next step |\n| `Failed` | Initialization failed; the system will auto-retry | Proceed to next step (retry is automatic) |\n| `Pending` | Awaiting activation; does **not** auto-recover | User must verify: 1) workspace exists, 2) the SLS project mapped to the workspace exists, 3) required logstores (`{workspace}__entity`, `{workspace}__topo`) exist under that project |\n\nExtract these variables for subsequent steps:\n\n| Field Path | Variable | Description |\n|-----------|----------|-------------|\n| `entryPointInfo.authToken` | **LicenseKey** | Agent authentication token (**sensitive - never print**) |\n| `entryPointInfo.publicDomain` | **publicEndpoint** | Public network data reporting endpoint |\n| `entryPointInfo.privateDomain` | **vpcEndpoint** | VPC internal data reporting endpoint |\n| `entryPointInfo.project` | **project** | SLS project name, used in OTel header `x-arms-project` |\n\n> **Credential Handling (mandatory)**: `authToken` is a data-reporting credential. Capture it into `ARMS_LICENSE_KEY` instead of printing it, never dump the raw `apm configuration get` JSON, and report only `LicenseKey: obtained (injected via ARMS_LICENSE_KEY)`. Full rules and the extraction recipe: [onboarding.md - Credential Output Redaction](onboarding.md#credential-output-redaction).\n\n### Step 4 - Register Application Service\n\n```bash\naliyun cms2 apm service create --workspace {workspace} --region {regionId} \\\n --body @service.json < /dev/null\n```\n\nWhere `service.json`:\n```json\n{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"TRACE\",\n \"attributes\": \"{\\\"language\\\":\\\"java\\\"}\"\n}\n```\n\n**serviceType mapping**:\n- proprietary agent (AliyunJavaAgent / instgo / aliyun-bootstrap / cms_node_sdk) -> `TRACE`\n- OpenTelemetry / eBPF -> `XTRACE`\n\n**`attributes.language` reference**:\n\n| Language | `attributes` value | serviceType |\n|----------|-------------------|-------------|\n| Java | omit or `{\"language\":\"java\"}` | TRACE or XTRACE |\n| Golang | `{\"language\":\"golang\"}` | TRACE or XTRACE |\n| Python | `{\"language\":\"python\"}` | TRACE or XTRACE |\n| Node.js | `{\"language\":\"nodejs\"}` | TRACE or XTRACE |\n| .NET | `{\"language\":\"dotnet\"}` | XTRACE |\n| PHP | `{\"language\":\"php\"}` | XTRACE |\n| Gateway (Nginx/Kong/APISIX) | omit | XTRACE |\n\n**Example real response**:\n```json\n{\n \"success\": true,\n \"data\": {\n \"pid\": \"awy7aw18hz@9269550ea2c2be0\",\n \"requestId\": \"B47F0659-143E-5E90-B446-29729C1ABC3A\",\n \"serviceId\": \"awy7aw18hz@645ab0bc177a46e87c7f1\"\n }\n}\n```\n\n### Step 5 - Generate Configuration Output\n\nRoute to the appropriate section below based on `language` + `method`, substitute the non-sensitive variables, and present to user for manual application. The LicenseKey stays an indirection - emit `$ARMS_LICENSE_KEY`, or leave `{LicenseKey}` unsubstituted in static config files and let the user fill it in ([Credential Output Redaction](onboarding.md#credential-output-redaction)).\n\n> **K8s users**: After generating configuration, proceed to [Step 6 - K8s Deployment Modification](#k8s-deployment-modification-step-6) to apply changes to the cluster.\n\n#### Addon Usage Decision Table\n\n| Scenario | `integration addon get` | Rationale |\n|----------|:-:|-----------|\n| Container / ACK / ACS / K8s onboarding | **Forbidden** | Use ack-onepilot component check + label patching directly |\n| ECS/host - Java AliyunJavaAgent (proprietary agent) | Not used | Only non-addon exception; use manual install section |\n| ECS/host - other proprietary agent (Go/Python) | **Use** | Fetch addon template (e.g. `apm-golang` -> `arms-ecs` protocol) |\n| ECS/host - OpenTelemetry (all languages) | **Use** | Standard addon Dynamic Fetch flow |\n| ack-onepilot component operations | **Forbidden** | `ack-onepilot` is a cluster component, not an addon name |\n\n> **User-facing prompt rule**: When asking the user to select onboarding type/protocol, always use \"Please select the onboarding type?\" as the question text. Do NOT use \"Please select the onboarding protocol type? (Addon type)\" or any phrasing that mentions \"Addon\" - this term is an internal implementation detail that is meaningless to users.\n\n> **Manual onboarding strategy**: By default, display the required startup parameters (e.g. `-javaagent`, `-Darms.*`, `OTEL_*` env vars) and guide the user to apply them manually. Also inform the user: if authorized, the agent can directly locate the target process startup script, auto-add parameters, and execute the restart. Explicit user authorization is required before performing any write or restart actions.\n>\n> **Manual alternative for all automated steps**: If the user prefers manual operation, provide:\n> - The exact commands/config to copy-paste\n> - The target file paths to edit\n> - The AgentLoop console URL for GUI-based operation: `https://cmsnext.console.aliyun.com/`\n\n---\n\n## Common Configuration Templates\n\n### OTel Environment Variables (Shared)\n\nAll OpenTelemetry-based integrations use the same export configuration. Substitute variables from Step 3.\nPrefer runtime `addon get` templates (see [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch)); use this section as fallback when addon templates are unavailable.\n\n**HTTP protocol** (recommended):\n```bash\nexport OTEL_SERVICE_NAME={appName}\nexport OTEL_RESOURCE_ATTRIBUTES=service.name={appName},acs.cms.workspace={workspace},service.version={version},deployment.environment={env}\nexport OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nexport OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://{endpoint}/opentelemetry/v1/traces\nexport OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://{endpoint}/opentelemetry/v1/metrics\n# ARMS_LICENSE_KEY is exported from apm configuration get (see onboarding.md); never inline the token\nexport OTEL_EXPORTER_OTLP_HEADERS=\"x-arms-license-key=$ARMS_LICENSE_KEY,x-arms-project={project},x-cms-workspace={workspace}\"\nexport OTEL_LOGS_EXPORTER=none\n```\n\n**gRPC protocol**:\n```bash\nexport OTEL_SERVICE_NAME={appName}\nexport OTEL_RESOURCE_ATTRIBUTES=service.name={appName},acs.cms.workspace={workspace},service.version={version},deployment.environment={env}\nexport OTEL_EXPORTER_OTLP_PROTOCOL=grpc\nexport OTEL_EXPORTER_OTLP_ENDPOINT=https://{endpoint}:10010\n# ARMS_LICENSE_KEY is exported from apm configuration get (see onboarding.md); never inline the token\nexport OTEL_EXPORTER_OTLP_HEADERS=\"x-arms-license-key=$ARMS_LICENSE_KEY,x-arms-project={project},x-cms-workspace={workspace}\"\nexport OTEL_LOGS_EXPORTER=none\n```\n\n> `{endpoint}` = `{publicEndpoint}` (public network) or `{vpcEndpoint}` (VPC internal).\n\n**Language-specific overrides**: Some languages use different endpoint path prefixes (e.g. `/apm/trace/opentelemetry/v1/traces` for Golang/Node.js). See per-language sections below.\n\n### ack-onepilot Labels (Shared)\n\nAll ack-onepilot onboarding uses these labels at `spec.template.metadata.labels`:\n\n```yaml\narmsPilotAutoEnable: \"on\"\narmsPilotCreateAppName: \"{appName}\"\narmsPilotAppWorkspace: \"{workspace}\"\n```\n\nAdditional labels by language:\n\n| Language | Extra Label | Notes |\n|----------|-------------|-------|\n| Java | `one-agent.jdk.version: \"OpenJDK18\"` | Optional, match app JDK version |\n| Golang | `aliyun.com/app-language: golang` | Required for non-Java |\n| Python | `aliyun.com/app-language: python` | Required for non-Java |\n\n> **Prerequisite**: ack-onepilot component must be installed and running. See [ack-onepilot Installation](#prerequisites-install-ack-onepilot-component).\n\n### Agent Download URL Pattern\n\n| Network | URL Pattern |\n|---------|-------------|\n| Public | `http://arms-apm-{regionId}.oss-{regionId}.aliyuncs.com/<path>` |\n| VPC | `http://arms-apm-{regionId}.oss-{regionId}-internal.aliyuncs.com/<path>` |\n\n---\n\n## OpenTelemetry Onboarding (Dynamic Fetch)\n\n> **STOP - CONTAINER EXCLUSION**: This entire section applies **ONLY to non-container (ECS/host) scenarios**. For container/ACK/ACS onboarding, skip directly to ack-onepilot component check + label patching. See [Addon Usage Decision Table](#addon-usage-decision-table).\n\nFor non-container onboarding, fetch the latest install guide at runtime instead of using static snippets.\n\n1. Select addon by target language/component:\n\n| Target | Addon Name |\n|--------|------------|\n| Java | `apm-java-batch` |\n| Golang | `apm-golang` |\n| Python | `apm-python` |\n| Node.js | `apm-nodejs-batch` |\n| PHP | `apm-php-batch` |\n| .NET | `apm-dotnet-batch` |\n| Nginx | `apm-nginx` |\n| Kong | `apm-kong` |\n| APISIX | `apm-apisix` |\n\n2. Fetch addon card:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json\n```\n\n3. Extract the target protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"opentelemetry\") | .codeTemplate'\n```\n\n4. Render variables with Step 3 credentials and runtime context:\n\n| Template Variable | Value Source |\n|-------------------|--------------|\n| `{{region}}` | `{regionId}` |\n| `{{LicenseKey}}` | `entryPointInfo.authToken` - render as `$ARMS_LICENSE_KEY`, never as the literal token |\n| `{{workspace}}` / `{{$context$.workspace}}` | `{workspace}` |\n| `{{Project}}` | `entryPointInfo.project` |\n| `{{PubDomain}}` / `{{PubAddr}}` | `entryPointInfo.publicDomain` |\n| `{{VpcDomain}}` / `{{InnerAddr}}` | `entryPointInfo.privateDomain` |\n| `{{serviceName}}` | `{appName}` |\n| `{{version}}` | Ask user (see interactive rules below) |\n| `{{environment}}` | Ask user (see interactive rules below) |\n| `{{connectionType}}` | `inner` (VPC) or `public` |\n| `{{exportMethod}}` | Must be selected from `schema.props.dataSource` |\n\n5. **Interactive parameter confirmation rules**:\n - For branch/select parameters (`connectionType`, `exportMethod`, `instrumentType`, `source`), ask the user to choose explicitly with concrete options from schema `dataSource`. Do NOT auto-select or silently use defaults.\n - For `{{version}}` and `{{environment}}`, always ask user to confirm with suggested defaults: `version` -> `1.0.0`, `2.0.0`, or custom; `environment` -> `production`, `staging`, `development`, or custom.\n - If schema and template disagree on allowed values, **schema wins**. Hidden branches not in schema are unavailable.\n - If schema is missing or invalid, switch to manual guidance mode (show raw template + ask user to confirm each field).\n - Only ask for parameters that are actually referenced by the selected template branch.\n\n6. Present rendered steps to user. If the addon template is unavailable, fallback to the per-language documentation linked in each section below.\n\n---\n\n## Java - AliyunJavaAgent (Manual Install)\n\n### 1. Download Agent\n\n```bash\nwget -T 30 -t 3 \"http://arms-apm-{regionId}.oss-{regionId}[-internal].aliyuncs.com/AliyunJavaAgent.zip\" -O AliyunJavaAgent.zip\nunzip AliyunJavaAgent.zip -d /opt/\n```\n\n### 2. Startup Configuration\n\n**Spring Boot / JAR**:\n```bash\n# ARMS_LICENSE_KEY is exported from apm configuration get (see onboarding.md); never inline the token\njava -javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar \\\n -Darms.licenseKey=\"$ARMS_LICENSE_KEY\" \\\n -Darms.appName={appName} \\\n -Darms.workspace={workspace} \\\n -jar app.jar\n```\n\n**Tomcat** - add to `{TOMCAT_HOME}/bin/setenv.sh`:\n```bash\nJAVA_OPTS=\"$JAVA_OPTS -javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar -Darms.licenseKey=$ARMS_LICENSE_KEY -Darms.appName={appName} -Darms.workspace={workspace}\"\n```\n\n**Jetty** - add to `{JETTY_HOME}/start.ini` (`start.ini` is not shell-expanded, so leave the placeholder and let the user paste their own LicenseKey):\n```\n--exec\n-javaagent:/opt/AliyunJavaAgent/aliyun-java-agent.jar\n-Darms.licenseKey={LicenseKey}\n-Darms.appName={appName}\n-Darms.workspace={workspace}\n```\n\n**Multi-instance**: add `-Darms.agentId=001` to differentiate JVM processes on the same host.\n\nReference: [Manually install Java agent](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-agent-for-java-applications).\n\n---\n\n## Java - OpenTelemetry Agent\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-java-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-java-batch --env-type Client -o json\n```\n\nFallback: [Report Java application data via OpenTelemetry](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-java-application-data).\n\n---\n\n## Java - ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nBefore adding labels, verify that the **ack-onepilot** component is installed and running in the target cluster.\n\n> **Caution**: Do NOT use `aliyun cs describe-cluster-addons-version` to check installation status - it returns all **available** addons (including uninstalled ones), not only installed ones.\n\n**Check** - use `kubectl` to verify actual resources:\n\n```bash\nkubectl get ns ack-onepilot\nkubectl get pods -n ack-onepilot\n```\n\nIf the namespace does not exist or no pods are Running, the component is **not installed**.\n\n**Install** - **WARNING: CONFIRMATION REQUIRED - Phase A**: Inform the user that ack-onepilot is not installed and present the installation plan. STOP and end your turn. Do NOT proceed until user explicitly confirms.\n\n```markdown\n### Execution Plan - Install ack-onepilot\n\n- Target: Cluster `[{clusterId}]`\n- Commands:\n - `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Precondition: ack-onepilot is not installed (`kubectl get ns ack-onepilot` returns NotFound)\n- Impact: deploys DaemonSet in `ack-onepilot` namespace; agent pods run on worker nodes\n- Rollback: `kubectl delete ns ack-onepilot` (or uninstall via console)\n\nPlease confirm installation (`yes` / `no`).\n```\n\n**Phase B** (after user confirms): Obtain `clusterId` via `aliyun cs describe-clusters`, then execute:\n\n```bash\naliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"\n```\n\nAfter installation, verify pods are Running:\n\n```bash\nkubectl get pods -n ack-onepilot\n```\n\n> **Permission requirement**: RAM account must have `cs:InstallClusterAddons` permission. If 403 Forbidden, fall back to manual installation via [Container Service Console](https://cs.console.aliyun.com/) -> Cluster -> Operations > Component Management -> Search `ack-onepilot` -> Install.\n>\n> **Manual alternative**: If the user cannot or prefers not to use CLI for component installation, guide them to the console path above. The result is identical.\n\n**Requirements**: ack-onepilot >= 5.1.0; Worker node RAM role needs `AliyunARMSFullAccess` and `AliyunTracingAnalysisFullAccess`.\n\n### Add Labels\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) to the Deployment. Java does not require the `aliyun.com/app-language` label.\n\nReference: [Onboard Java applications via ack-onepilot](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-the-arms-agent-for-java-applications-deployed-in-ack-and-acs-clusters-by-using-the-ack-onepilot-component).\n\n---\n\n## Golang - Onboarding (via `apm-golang` addon)\n\nAll Golang onboarding methods (proprietary agent instgo and OpenTelemetry) use the same addon for template rendering:\n\n```bash\naliyun cms2 integration addon get --addon-name apm-golang --env-type Client -o json\n```\n\nSelect the protocol template by method:\n\n| Method | Protocol Name in Addon | Notes |\n|--------|----------------------|-------|\n| proprietary agent (ECS/host) | `arms-ecs` | instgo compile-time instrumentation |\n| OpenTelemetry (Auto) | `opentelemetry` | Standard OTel Dynamic Fetch flow |\n| OpenTelemetry (Manual SDK) | `opentelemetry` | Prefer SDK instructions in template if available |\n\n> For ACK/K8s container onboarding, do NOT use this addon flow. Follow [Golang - ack-onepilot (K8s)](#golang--ack-onepilot-k8s) directly.\n\nExtract a specific protocol template:\n\n```bash\naliyun cms2 integration addon get --addon-name apm-golang --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocolName}\") | .codeTemplate'\n```\n\nFallback: [Manually install Golang agent](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-golang-agent) | [Report Go application data via OpenTelemetry](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-go-application-data).\n\n---\n\n## Golang - ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nFollow the same installation and confirmation workflow as [Java - ack-onepilot (K8s)](#java--ack-onepilot-k8s):\n- Check installation status with `kubectl get ns ack-onepilot` and `kubectl get pods -n ack-onepilot`\n- If missing, use **Two-Phase confirmation** before installation\n- In container onboarding, do not ask user for `regionId`\n- Install command (after user confirms):\n `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Verify all ack-onepilot pods are `Running` before continuing\n- Do NOT run `integration addon list/get` to search for `ack-onepilot`\n\n### Add Labels to Deployment\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) with `aliyun.com/app-language: golang`.\n\n**Important**: Golang applications require compiling with `instgo` before deploying to K8s. The ack-onepilot component handles agent injection, but the binary must already be instrumented at compile time.\n\nReference: [Onboard Go applications via ack-onepilot](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-arms-agent-for-golang-applications-deployed-in-ack-and-acs).\n\n---\n\n## Python - Aliyun Agent (aliyun-bootstrap)\n\n```bash\npip3 install aliyun-bootstrap\naliyun-bootstrap -a install\n\nexport ARMS_APP_NAME={appName}\nexport ARMS_WORKSPACE={workspace}\nexport ARMS_REGION_ID={regionId}\n# Capture the LicenseKey without printing it (see onboarding.md#credential-output-redaction)\nexport ARMS_LICENSE_KEY=\"$(aliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json | jq -r '.data.entryPointInfo.authToken')\"\n\naliyun-instrument python app.py\n```\n\n**Special cases**:\n- **uvicorn**: `from aliyun.opentelemetry.instrumentation.auto_instrumentation import sitecustomize` as first import, or `aliyun-instrument gunicorn -k uvicorn.workers.UvicornWorker ...`\n- **uWSGI**: see [uWSGI integration docs](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-python-agent)\n- **gevent**: set `GEVENT_ENABLE=true`\n- **AI frameworks** (LangChain/LangGraph, DashScope, AgentScope, OpenAI and others): Some AI frameworks reuse this Python agent via the `arms`/`arms4cs` protocols. See [references/ai.md](ai.md) for the full AI observability onboarding guide.\n\n**Docker**:\n```dockerfile\nENV ARMS_APP_NAME={appName}\nENV ARMS_REGION_ID={regionId}\nENV ARMS_WORKSPACE={workspace}\n# Do NOT bake the LicenseKey into the image; inject it at runtime:\n#   docker run -e ARMS_LICENSE_KEY=\"$ARMS_LICENSE_KEY\" ...\nRUN pip3 install aliyun-bootstrap && ARMS_REGION_ID={regionId} aliyun-bootstrap -a install\nCMD [\"aliyun-instrument\", \"python\", \"app.py\"]\n```\n\nReference: [Manually install Python agent](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-the-python-agent).\n\n---\n\n## Python - OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-python`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-python --env-type Client -o json\n```\n\nFallback: [Report Python application data via OpenTelemetry](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-python-application-data).\n\n---\n\n## Python - ack-onepilot (K8s)\n\n### Prerequisites: Install ack-onepilot Component\n\nFollow the same installation and confirmation workflow as [Java - ack-onepilot (K8s)](#java--ack-onepilot-k8s):\n- Check installation status with `kubectl get ns ack-onepilot` and `kubectl get pods -n ack-onepilot`\n- If missing, use **Two-Phase confirmation** before installation\n- In container onboarding, do not ask user for `regionId`\n- Install command (after user confirms):\n `aliyun cs install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot config=\"\" version=\"\"`\n- Verify all ack-onepilot pods are `Running` before continuing\n- Do NOT run `integration addon list/get` to search for `ack-onepilot`\n\n### Add Labels to Deployment\n\nApply [ack-onepilot labels from Common Configuration](#ack-onepilot-labels-shared) with `aliyun.com/app-language: python`.\n\nFor ack-onepilot >= 5.1.0, the Python agent is auto-injected - no Dockerfile modification needed.\n\nReference: [Onboard Python applications via ack-onepilot](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/install-arms-agent-for-python-applications-deployed-in-ack-and-acs).\n\n---\n\n## Node.js - proprietary Node SDK (proprietary agent)\n\n### Prerequisites\n\n- Node.js v16+ (Active or Maintenance LTS versions only)\n- Supported frameworks: Express, Koa, HTTP/HTTPS, MySQL, PostgreSQL, MongoDB, Redis, Kafka, gRPC, Socket.IO\n\n### 1. Install\n\n```bash\nnpm install @loongsuite/cms_node_sdk\n```\n\n### 2. Start Application\n\n**CommonJS mode**:\n```bash\nexport ARMS_LICENSE=\"$ARMS_LICENSE_KEY\" # exported from apm configuration get; never inline the token\nexport CMS_SERVICE_NAME={appName}\nexport ARMS_REGION_ID={regionId}\nexport ARMS_WORKSPACE={workspace}\nnode -r @loongsuite/cms_node_sdk/register app.js\n```\n\n**ESModule mode**:\n```bash\nexport ARMS_LICENSE=\"$ARMS_LICENSE_KEY\" # exported from apm configuration get; never inline the token\nexport CMS_SERVICE_NAME={appName}\nexport ARMS_REGION_ID={regionId}\nexport ARMS_WORKSPACE={workspace}\nnode --experimental-loader=@loongsuite/cms_node_sdk/import-hooks -r @loongsuite/cms_node_sdk/register index.js\n```\n\n### 3. Manual Instrumentation (Optional)\n\nCreate `instrumentation.js`:\n\n**CommonJS**:\n```javascript\nconst { NodeSDK } = require('@loongsuite/cms_node_sdk');\n\nconst sdk = new NodeSDK({\n serviceName: \"{appName}\",\n licenseKey: process.env.ARMS_LICENSE_KEY,\n regionId: \"{regionId}\",\n workspace: \"{workspace}\",\n});\n\nsdk.start();\nmodule.exports = sdk;\n```\n\n**ESModule**:\n```javascript\nimport { NodeSDK } from '@loongsuite/cms_node_sdk';\n\nconst sdk = new NodeSDK({\n serviceName: \"{appName}\",\n licenseKey: process.env.ARMS_LICENSE_KEY,\n regionId: \"{regionId}\",\n workspace: \"{workspace}\",\n});\n\nsdk.start();\nexport { sdk };\n```\n\nRun with:\n```bash\nnode --require ./instrumentation.js app.js\n```\n\n---\n\n## Node.js - OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-nodejs-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-nodejs-batch --env-type Client -o json\n```\n\nFallback: [Node.js OpenTelemetry onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-node-js-application-data).\n\n---\n\n## PHP - OpenTelemetry\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-php-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-php-batch --env-type Client -o json\n```\n\nFallback: [PHP OpenTelemetry onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-php-application-data).\n\n---\n\n## .NET - OpenTelemetry (Auto-Instrument)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-dotnet-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json\n```\n\nFallback: [.NET OpenTelemetry onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-net-application-data).\n\n---\n\n## .NET - OpenTelemetry (Manual SDK)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-dotnet-batch`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json\n```\n\nPrefer codeTemplate content that includes manual SDK instructions when available in the current addon version.\n\nFallback: [.NET OpenTelemetry onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/use-opentelemetry-to-report-net-application-data).\n\n---\n\n## .NET - eBPF (OBI DaemonSet)\n\nUse addon template runtime fetch from `apm-dotnet-batch` with OBI protocol card.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-dotnet-batch --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"obi\") | .codeTemplate'\n```\n\nFallback: [eBPF ECS onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/access-observable-through-opentelemetry-ebpf-obi-on-ecs) | [eBPF ACK onboarding guide](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/access-observable-through-opentelemetry-ebpf-obi-on-ack).\n\n---\n\n## Nginx - OpenTelemetry (ngx_otel_module)\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-nginx`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-nginx --env-type Client -o json\n```\n\nFallback: complete onboarding via [AgentLoop console > Integration Center](https://agentloop.console.aliyun.com/).\n\n---\n\n## Kong - OpenTelemetry Plugin\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-kong`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-kong --env-type Client -o json\n```\n\nFallback: complete onboarding via [AgentLoop console > Integration Center](https://agentloop.console.aliyun.com/).\n\n---\n\n## APISIX - OpenTelemetry Plugin\n\nUse [OpenTelemetry Onboarding (Dynamic Fetch)](#opentelemetry-onboarding-dynamic-fetch) with addon `apm-apisix`.\n\n```bash\naliyun cms2 integration addon get --addon-name apm-apisix --env-type Client -o json\n```\n\nFallback: complete onboarding via [AgentLoop console > Integration Center](https://agentloop.console.aliyun.com/).\n\n---\n\n## Post-Onboarding Verification\n\n```bash\n# Verify the service was registered\naliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json\n```\n\n**Expected**: service appears with correct `serviceType` and `serviceName`. After restarting the application, data should appear in AgentLoop console within 2-3 minutes.\n\n---\n\n## Offboarding / Uninstall\n\nOffboarding is the reverse of onboarding. The general principle: **remove agent configuration from the application first, then clean up AgentLoop platform resources**.\n\n### Generic Uninstall Steps\n\n| Step | Action | Command / Procedure |\n|------|--------|---------------------|\n| 1 | Remove agent from application | Reverse of Step 5: remove `-javaagent`, `OTEL_*` env vars, `aliyun-instrument` wrapper, or ack-onepilot labels |\n| 2 | Restart application | Restart without agent params; for K8s, removing labels triggers rolling update automatically |\n| 3 | Verify agent stopped | Confirm no new data appears in AgentLoop console after 3-5 minutes |\n| 4 | Delete service record (optional, **requires user confirmation**) | `aliyun cms2 apm service delete --workspace {workspace} --service-id {serviceId} --region {regionId}` |\n\n### Uninstall by Method\n\n| Method | What to Remove |\n|--------|----------------|\n| **proprietary agent (JVM)** | Remove `-javaagent:/opt/AliyunJavaAgent/...` and all `-Darms.*` from startup command; optionally `rm -rf /opt/AliyunJavaAgent` |\n| **proprietary agent (Golang)** | Re-compile without `instgo` (`go build` instead of `./instgo go build`); remove `ARMS_*` env vars |\n| **proprietary agent (Python)** | Remove `aliyun-instrument` wrapper from CMD; `pip3 uninstall aliyun-bootstrap`; remove `ARMS_*` env vars |\n| **proprietary agent (Node.js)** | Remove `-r @loongsuite/cms_node_sdk/register` from startup; `npm uninstall @loongsuite/cms_node_sdk`; remove `ARMS_*`/`CMS_*` env vars |\n| **OpenTelemetry** | Remove `-javaagent:opentelemetry-javaagent.jar` or `opentelemetry-instrument` wrapper; remove all `OTEL_*` env vars |\n| **ack-onepilot** | Remove labels (`armsPilotAutoEnable`, `armsPilotCreateAppName`, `armsPilotAppWorkspace`, `aliyun.com/app-language`) from Deployment |\n| **eBPF (OBI)** | `kubectl delete daemonset obi -n {namespace}` + delete ConfigMap and RBAC |\n| **Gateway plugins** | Remove `opentelemetry` plugin config from Nginx/Kong/APISIX |\n\n### ack-onepilot Component Uninstall (Cluster-wide)\n\nOnly when removing APM from the entire cluster:\n\n```bash\naliyun cs un-install-cluster-addons --cluster-id {clusterId} --biz-body name=ack-onepilot\n```\n\n> **Caution - CONFIRMATION REQUIRED**: This affects ALL monitored applications in the cluster. Use Two-Phase Protocol.\n\n> **Manual alternative**: Container Service Console -> Cluster -> Operations > Component Management -> Search `ack-onepilot` -> Uninstall.\n\n---\n\n## Error Handling\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `ServiceObservability not exists` (404) | APM not initialized for this workspace | Run `apm configuration create` first |\n| `The workspace does not belong to you` (401) | Workspace not owned by current account, or wrong workspace provided | Ask user to confirm the `agentloop-` AgentLoop workspace name; verify AccountId via `aliyun sts get-caller-identity` |\n| `CredentialNotConfigured` | Missing AK/SK | Run `aliyun configure` to set up the default credential profile (see [onboarding.md - Credentials](onboarding.md#credentials)) |\n| `--body and stdin are mutually exclusive` | Shell stdin conflict with `--body` | Append `< /dev/null` to the command, or use `--body @file.json` |\n\n---\n\n## Agent Download URLs by Region\n\nSee [Agent Download URL Pattern](#agent-download-url-pattern) in Common Configuration. Region list:\n\n| Region | regionId |\n|--------|----------|\n| East China 1 (Hangzhou) | `cn-hangzhou` |\n| East China 2 (Shanghai) | `cn-shanghai` |\n| North China 2 (Beijing) | `cn-beijing` |\n| South China 1 (Shenzhen) | `cn-shenzhen` |\n| China (Hong Kong) | `cn-hongkong` |\n| Singapore | `ap-southeast-1` |\n| US (Silicon Valley) | `us-west-1` |\n| Europe (Frankfurt) | `eu-central-1` |\n\nFull region list: [Manual Agent Installation](https://help.aliyun.com/zh/cms/cloudmonitor-2-0/manually-install-agent-for-java-applications)\n\n---\n\n## K8s Deployment Modification (Step 6)\n\nAfter generating the configuration (Step 5), if the user's application runs on Kubernetes, patch the Deployment YAML to inject the onboarding labels/env vars - with explicit user confirmation before applying.\n\n> **Scope**: For **ack-onepilot** method, this step is **required** - label patching IS the onboarding mechanism. For other methods (manual startup / OTel env vars), this step is optional (user may prefer to modify their own manifests).\n\n> **Safety rule**: ALL cluster write operations - including installing components (e.g. ack-onepilot) and patching Deployments - require **explicit user confirmation** before execution. Show the user what will be changed and wait for approval.\n\n> **Manual alternative**: If the user prefers not to use automated patching, provide the label/env YAML snippet and instruct them to:\n> 1. Edit Deployment YAML manually: `kubectl edit deployment {name} -n {namespace}`\n> 2. Or apply via console: Container Service Console -> Workloads -> Deployments -> Edit YAML\n> 3. Or use a GitOps workflow: commit the label changes to their deployment manifest repository\n\n### Prerequisites\n\n- `kubectl` CLI is available locally\n- AK/SK has ACK cluster read permissions (`cs:DescribeClusters`, `cs:DescribeClusterUserKubeconfig`)\n- For ack-onepilot method: verify component is installed first. See [ack-onepilot Prerequisites](#prerequisites-install-ack-onepilot-component) for check and installation steps\n- In container onboarding, do not ask user for `regionId`; derive it automatically from cluster metadata or kubeconfig context when needed\n\n### Workflow\n\n1. **Discover clusters and obtain kubeconfig**:\n\n ```bash\n # List ACK clusters to find clusterId (only needed when clusterId is unknown)\n aliyun cs describe-clusters --region {regionId}\n\n # Get kubeconfig for the target cluster (saved to ~/.kube/config by default)\n aliyun cs describe-cluster-user-kubeconfig --cluster-id {clusterId} --temporary-duration-minutes 480\n ```\n\n If the user's cluster is not ACK (self-managed K8s), ask for the kubeconfig file path (default `~/.kube/config`).\n\n Verify access:\n ```bash\n kubectl cluster-info\n ```\n\n2. **Search for Deployment across namespaces**:\n\n ```bash\n kubectl get deployment --all-namespaces -o wide\n ```\n\n Filter results by user-provided deployment name or `{appName}`. If multiple matches are found, present the list (name + namespace + replicas) and ask the user to confirm the target. If no match is found, ask the user for the exact deployment name or namespace. Note: deployment name and `appName` are independent - do NOT use deployment name as `appName` without explicit user confirmation.\n\n3. **Read current Deployment**:\n\n ```bash\n kubectl get deployment {deploymentName} -n {namespace} -o yaml\n ```\n\n4. **WARNING: CONFIRMATION REQUIRED - Phase A**: Show patch to user and STOP. End your turn here. Do NOT apply the patch in the same response.\n\n Present the following to the user:\n\n ```markdown\n ### Execution Plan - Patch K8s Deployment\n\n - Target: `{namespace}/{deploymentName}`\n - Current replicas: `{replicas}`\n - Action: add APM onboarding labels/env\n - Patch JSON:\n ```json\n {full patch content}\n ```\n - Impact: triggers Deployment rolling update; pods will be recreated\n - Rollback: `kubectl rollout undo deployment/{deploymentName} -n {namespace}`\n\n Please confirm execution (`yes` / `no`).\n ```\n\n **STOP HERE. End your turn. Wait for user's next message.**\n\n5. **Phase B - Apply patch** (ONLY after user's next message contains explicit approval):\n\n **ack-onepilot method** - patch labels:\n\n ```bash\n # Java (no app-language label needed):\n kubectl patch deployment {deploymentName} -n {namespace} \\\n --type=strategic -p '{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"armsPilotAutoEnable\":\"on\",\"armsPilotCreateAppName\":\"{appName}\",\"armsPilotAppWorkspace\":\"{workspace}\"}}}}}'\n\n # Non-Java (add aliyun.com/app-language):\n kubectl patch deployment {deploymentName} -n {namespace} \\\n --type=strategic -p '{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"aliyun.com/app-language\":\"{language}\",\"armsPilotAutoEnable\":\"on\",\"armsPilotCreateAppName\":\"{appName}\",\"armsPilotAppWorkspace\":\"{workspace}\"}}}}}'\n ```\n\n **OpenTelemetry method** - add `OTEL_*` env vars to container spec (see [OTel env vars](#otel-environment-variables-shared)).\n\n6. **Verify rollout**:\n\n ```bash\n kubectl rollout status deployment/{deploymentName} -n {namespace} --timeout=120s\n ```\n\n### Safety Checklist\n\nBefore executing any K8s write operation (component installation or Deployment patch):\n- [ ] Presented complete execution plan (Phase A) in a dedicated response\n- [ ] **Ended turn after Phase A** - did NOT continue to execution in the same response\n- [ ] User's NEXT message contains explicit approval (\"yes\"/\"confirm\"/\"proceed\"/\"go ahead\")\n- [ ] For component installation (e.g. ack-onepilot): informed user the component is missing, got Phase A confirmation\n- [ ] Searched across all namespaces first, then confirmed deployment name and namespace with user\n- [ ] Showed the complete patch JSON/YAML to user in Phase A\n- [ ] Verified current replica count to understand blast radius\n- [ ] After patching (Phase B), verified rollout status\n- [ ] If rollout fails, guided user to rollback: `kubectl rollout undo deployment/{name}`\n\n---\n\n## Troubleshooting\n\n| Symptom | Check |\n|---------|-------|\n| Agent not reporting | Verify LicenseKey, workspace, endpoint; check network (ports 80/443 outbound) |\n| App not in console | Confirm workspace matches; wait 2-3 min for data propagation |\n| K8s pod not monitored | ack-onepilot >= 5.1.0 installed; labels on `spec.template.metadata.labels` (not top-level) |\n| OTel data missing | Check `x-arms-license-key` and `x-cms-workspace` headers |\n| Different workspace LicenseKey mismatch | Each workspace has its own LicenseKey - do NOT reuse across workspaces |\n\nFile v0.1.5:references/dataset/data-operations.md\n\n# Dataset Data Operations\n\n## Append Structured Rows\n\nPrefer `add-dataset-data` for normal inserts. It accepts typed JSON and avoids SQL escaping mistakes.\n\n```bash\naliyun agentloop add-dataset-data \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --data-array '[\n    {\n      \"question\":\"How do I inspect an error?\",\n      \"answer\":\"Start with the request ID.\",\n      \"score\":0.95,\n      \"metadata\":{\"source\":\"manual\",\"latency_ms\":120}\n    },\n    {\n      \"question\":\"How do I retry safely?\",\n      \"answer\":\"Reuse the same idempotency token.\",\n      \"score\":0.91,\n      \"metadata\":{\"source\":\"reviewed\",\"latency_ms\":85}\n    }\n  ]' \\\n  --client-token <client_token>\n```\n\nRules:\n\n- `dataArray` cannot be empty and every item must be a JSON object.\n- All rows in one request are committed atomically.\n- The maximum request body is 100 MiB (`100 * 1024 * 1024` bytes). There is no separate fixed API row-count limit; the server streams rows and keeps the request atomic.\n- Unknown fields fail the whole request.\n- Missing schema fields are stored as `null`.\n- Field names are matched case-insensitively; duplicate case variants are rejected.\n- `text` accepts strings, `long` accepts integers, `double` accepts finite numbers, and `json` accepts any valid JSON value.\n- Omit `id` to auto-generate it. A supplied `id` must be a UUID.\n- Omit `__time__` to use the current Unix time. A supplied value must be non-null and a non-negative integer in seconds.\n- Never supply `__dataset_seq`.\n\nBefore dry-run, compare every row's keys and nested values with the user's requested data, separately from schema validation. The payload may contain only user-authorized fields supported by the schema, plus system fields the user explicitly supplied. Existing optional schema fields may remain omitted; their presence is not permission to populate them. If the user requests a marker in `agentloop_annotations`, keep it inside that object, even if the schema also has a top-level `marker_id`. Do not add or duplicate a field to make verification easier.\n\nDry-run complex row-array structure and inspect that booleans, numbers, objects, arrays, and null values retain their JSON types. If rows contain real prompts, outputs, tokens, PII, or other sensitive content, use a shape-equivalent synthetic array for dry-run; do not print the real request body into terminal history or conversation output:\n\n```bash\naliyun agentloop add-dataset-data \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --data-array '<json_array>' \\\n  --client-token <client_token> \\\n  --cli-dry-run\n```\n\nSuccess returns `requestId` and `affectedRows`. Verify `affectedRows` equals the submitted row count, then query a narrow sample.\n\nUse the same authorized field structure for the serialized dry-run body and the real write. Successful serialization or API acceptance does not prove that extra fields were requested. When the requested readback predicate cannot select a nested marker, use the user's authorized predicate and inspect the marker in returned rows; do not change the write payload or schema to create a more convenient filter.\n\n### Numeric-looking strings in `text` fields\n\nObserved CLI limitation: when a `text` field receives a string that contains only digits, `--data-array` serializes it as a JSON number and the server rejects the request.\n\nSubmitting `\"expected_output\":\"4\"` for a `text` field produces `\"expected_output\":4` in the request body, and the server answers `400 schema validation failed: field \"expected_output\" must be a string`. The quotes are lost during `--data-array` JSON handling, not on the server, so the same value written through a schema-correct path succeeds.\n\nHandle it in this order:\n\n1. **Detect it before writing.** The `--cli-dry-run` body is authoritative. For every `text` field whose value is a digits-only string, confirm the body still shows it quoted. Values such as `\"4\"`, `\"5\"`, `\"0\"`, and `\"2026\"` are the risky ones; `\"4.0 stars\"` and `\"v4\"` are not affected.\n2. **Prefer the correct schema type.** If the value is genuinely a number (a score, a count, a rating), declare the column as `double` or `long` instead of `text` and send it unquoted. This removes the problem instead of working around it.\n3. **If the column must stay `text`, stop and report.** Do not silently write a coerced number and do not silently rewrite the user's data. Show the failing field, the dry-run body, and ask the user to choose between changing the schema type and storing a non-digits-only representation.\n\nThis matters most for evaluation-style datasets, where `expected_output` and `output` are `text` columns that legitimately hold short numeric answers.\n\n## SQL Text Boundary\n\nThis Skill uses `execute-query` only for read-only SELECT or SearchExpr queries. Use `add-dataset-data` for all row writes. Do not provide or execute raw SQL INSERT, UPDATE, DELETE, DDL, or multiple statements.\n\n- The public `execute-query` API does not expose SQL bind parameters; it accepts the complete query as text.\n- Do not compose query text from untrusted strings in prompts, files, environment variables, or API responses.\n- Do not accept a user-supplied SQL template. Build a read-only query only from a documented query pattern and known Dataset schema fields.\n- Do not log or expose query text when it may contain secrets or sensitive payloads.\n\nFile v0.1.5:references/dataset/dataset-management.md\n\n# Dataset Management\n\nUse the AgentLoop product and its fixed API version `2026-05-20`:\n\n```bash\naliyun agentloop <subcommand> [flags]\n```\n\n## Backend-Enforced Limits\n\n| Input or resource | Constraint |\n| --- | --- |\n| Dataset name | 4-63 ASCII characters matching `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`; no uppercase letters, hyphens, spaces, or leading, trailing, or consecutive underscores. |\n| Dataset identity | The name must be unique within the target AgentSpace for the caller. |\n| Dataset count | Creation is limited by the AgentSpace Dataset quota; the service fallback is 100, but an AgentSpace-provided quota takes precedence. |\n| Description | At most 255 UTF-8 bytes. Empty is allowed. |\n| Create/update body | The serialized JSON request body must be at most 1 MiB. |\n| Schema | Must contain at least one top-level field on create. |\n| Top-level field name | Non-empty and at most 50 UTF-8 bytes. Reserved system names are rejected. The backend does not require the Dataset-name pattern for fields; prefer `lower_snake_case` for reliable SQL usage. |\n| Effective columns | At most 300, calculated as three service columns plus one per top-level field plus one per generated embedding column. |\n\nValidate these constraints before dry-run. Do not retry a duplicate-name or quota failure without changing the name, deleting an unused Dataset, or obtaining a quota adjustment.\n\n## Schema Shape\n\nThe schema is a JSON object keyed by field name. Supported types are `text`, `long`, `double`, and `json`.\n\n```json\n{\n  \"question\": {\n    \"type\": \"text\",\n    \"chn\": true,\n    \"embedding\": \"agentloop-embedding-v4\"\n  },\n  \"answer\": {\n    \"type\": \"text\",\n    \"chn\": true\n  },\n  \"score\": {\n    \"type\": \"double\"\n  },\n  \"metadata\": {\n    \"type\": \"json\",\n    \"jsonKeys\": {\n      \"source\": {\"type\": \"text\"},\n      \"latency_ms\": {\"type\": \"long\"}\n    }\n  }\n}\n```\n\nUse `embedding` only for top-level `text` or `json`. The only supported public value is `agentloop-embedding-v4`; internal backend model names are not valid public schema values. Each `jsonKeys` child uses `type` and optional `chn`; the current CLI does not expose child `embedding` or a deeper `jsonKeys` level. Do not define `id`, `__time__`, `__dataset_seq`, `__effective_seq`, or `__expired_seq`. Avoid top-level field names that differ only by case because structured row writes resolve fields case-insensitively.\n\n## Create\n\n```bash\naliyun agentloop create-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --description \"<description>\" \\\n  --schema '{\n    \"question\":{\"type\":\"text\",\"chn\":true,\"embedding\":\"agentloop-embedding-v4\"},\n    \"answer\":{\"type\":\"text\",\"chn\":true},\n    \"score\":{\"type\":\"double\"},\n    \"metadata\":{\"type\":\"json\",\"jsonKeys\":{\"source\":{\"type\":\"text\"},\"latency_ms\":{\"type\":\"long\"}}}\n  }' \\\n  --client-token <client_token>\n```\n\nBefore executing, append `--cli-dry-run` and verify that the body contains `datasetName`, `description`, and the typed `schema` object.\n\nAlso verify that the serialized body is no larger than 1 MiB, the description is no larger than 255 UTF-8 bytes, and the effective-column calculation does not exceed 300.\n\n## Get\n\n`get-dataset` returns the full public schema.\n\n```bash\naliyun agentloop get-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name>\n```\n\n## List and Paginate\n\n`--dataset-name` is an optional name filter. `maxResults` defaults to 100 and accepts 1-100.\n\n```bash\naliyun agentloop list-datasets \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <optional_name_filter> \\\n  --max-results 100\n```\n\nFor the next page, reuse the prior response's `nextToken` without modifying it:\n\n```bash\naliyun agentloop list-datasets \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --max-results 100 \\\n  --next-token '<next_token>'\n```\n\nDo not change the name filter between pages because the pagination token is bound to the list conditions.\n\n## Update Description\n\nKeep the new description at 255 UTF-8 bytes or fewer.\n\n```bash\naliyun agentloop update-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --description \"<new_description>\" \\\n  --client-token <client_token>\n```\n\n## Add Schema Fields\n\nFetch the Dataset first. Build `--schema` from only new top-level fields; omitted existing fields remain unchanged.\n\n```bash\naliyun agentloop update-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --schema '{\"reviewer\":{\"type\":\"text\"},\"review_score\":{\"type\":\"double\"}}' \\\n  --client-token <client_token>\n```\n\nDo not change or remove existing field definitions. In particular, do not change an existing field's type, `chn`, `embedding`, or nested `jsonKeys` structure.\n\n## Delete\n\n`delete-dataset` removes the Dataset and every row in it. There is no undo, no soft-delete window, and no per-row deletion command: this is the only supported way to remove Dataset data, so it is also the command reached for when the intent is merely \"clean up test rows\".\n\n```bash\naliyun agentloop delete-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name>\n```\n\nMeasured surface: `--agent-space` and `--dataset-name` are the only required flags. **`delete-dataset` accepts no `--client-token`**, unlike create, update, and `add-dataset-data`. A retry after an ambiguous failure is therefore not idempotent-by-token; re-check with `get-dataset` instead of blindly resending.\n\nRequired protocol before executing:\n\n1. Run `get-dataset` and show the user the exact Dataset name, AgentSpace, region, and schema that will be destroyed.\n2. Report the row count so the user sees the size of what is being deleted:\n   ```bash\n   aliyun agentloop execute-query \\\n     --region <region_id> \\\n     --agent-space <agent_space_name> \\\n     --dataset-name <dataset_name> \\\n     --type SQL \\\n     --query 'SELECT COUNT(*) AS row_count FROM <dataset_name>'\n   ```\n3. Get explicit confirmation for that one named Dataset. Do not accept a prior approval given for a different Dataset, and do not accept a pattern or wildcard as authorization.\n4. Delete one Dataset per command. Never loop over `list-datasets` output to delete in bulk, even when the user asks for a cleanup.\n5. Verify with `get-dataset`, which must then report the Dataset as absent.\n\nCheck for dependents first. A Pipeline whose sink is this Dataset keeps writing to a name that no longer exists, and an evaluation task reading it will fail. Search for a Pipeline sink pointing at the Dataset before deleting it, and tell the user what will break.\n\nDeleting and recreating a Dataset under the same name is not a schema-migration tool. Schema updates are add-only by design; if the user wants to change a field type, say so explicitly rather than silently proposing delete-then-recreate, because the rows are lost.\n\n## Structural Migration After Materialization\n\nAn add-only schema update changes the schema definition; it does not backfill rows already written. If a Pipeline or bulk import populated a Dataset without required fields such as raw `input`, raw `output`, or lineage, do not treat an in-place schema extension as a repair:\n\n1. Freeze the corrected output and consumer field contract.\n2. Preserve the existing Dataset as migration evidence.\n3. Create a versioned Dataset with the complete corrected schema.\n4. Create a versioned Pipeline or import job that emits every required field.\n5. Preview and reconcile the new target against the original source using `references/pipeline/verification-method.md`.\n6. Smoke-test downstream Evaluation or Experiment variable mapping.\n7. Switch consumers only after acceptance. Delete the old Dataset only when the user explicitly authorizes cleanup.\n\nRerunning corrected output into the old Dataset can mix old null rows with new rows and can duplicate source records. A create/update `clientToken` is not a Dataset-row deduplication key.\n\nFile v0.1.5:references/dataset/dataset.md\n\n# AgentLoop Dataset Skill\n\n> **Domain entry**: this file is the Dataset-domain playbook dispatched from the router SKILL.md of `alibabacloud-agentloop-management`. All file paths below are relative to the skill root.\n\n## Scenario\n\nOperate the public AgentLoop Dataset surface through `aliyun agentloop`:\n\n- Manage Dataset resources and schemas, including deletion.\n- Append typed structured rows without constructing INSERT SQL.\n- Query data with read-only `execute-query`.\n- Run full-text, semantic, SQL, or search-pipe-SQL retrieval.\n\nDo not expose or operate service deployment, database, cache, or other internal implementation details. Do not manage AgentSpaces unless the user separately requests that scope.\n\nTreat commands and parameters exposed by the installed public AgentLoop CLI plugin as the external capability boundary. Do not expose a capability found only in backend development code until it appears in the published CLI help or public API contract.\n\n## CLI Prerequisites\n\n**Require Aliyun CLI 3.3.15 or later.**\n\n```bash\naliyun version\n```\n\n**Require the AgentLoop plugin 0.7.1 or later.** This version exposes all Dataset commands used by this skill, including `add-dataset-data` and the extended `execute-query` parameters.\n\n```bash\naliyun plugin show --name agentloop\n```\n\nIf the AgentLoop plugin is missing or older than 0.7.1, install it through the configured Aliyun CLI plugin source, then verify it before continuing:\n\n```bash\naliyun plugin install --names agentloop\naliyun plugin show --name agentloop\n```\n\nUse the plugin ID `agentloop` for installation; successful output identifies the installed package as `aliyun-cli-agentloop`. If the Aliyun CLI itself is missing or below 3.3.15, stop and ask the user to upgrade the CLI through their organization-approved process outside this session. Do not download or install CLI binaries from this Skill.\n\n## Authentication\n\nUse an existing Aliyun CLI profile, Alibaba Cloud environment credentials, STS, OAuth, or an instance RAM role.\n\nSecurity rules:\n\n- Never read, echo, print, or paste AccessKey IDs, AccessKey secrets, security tokens, or other credentials.\n- Never ask the user to pass literal credentials in a command or conversation.\n- Never run `aliyun configure set` with literal credential values.\n- Use only `aliyun configure list` to check whether a usable identity and region are configured.\n- This restriction also applies while diagnosing `403 Forbidden`: do not run `aliyun configure get`, read `.aliyun/config.json`, or dump credential environment variables. A permission denial is not permission to inspect secret values; use the denied action and request ID for diagnosis.\n\n```bash\naliyun configure list\n```\n\nIf no valid identity is available, stop and ask the user to configure credentials outside this session. Do not continue to a Dataset request.\n\n## RAM Permissions\n\nDataset operations use the seven concrete RAM actions listed in `references/dataset/ram-policies.md` and support Dataset resource ARNs. Do not use a wildcard action pattern in a policy. `agentloop:DeleteDataset` is not part of the default least-privilege template; treat a missing-delete-permission failure as expected unless the identity was explicitly granted deletion.\n\nOn any permission failure:\n\n1. Capture the API action, denied RAM action, and request ID without exposing credentials.\n2. Read `references/dataset/ram-policies.md`.\n3. If `ram-permission-diagnose` is installed, invoke it. Otherwise show the missing action and the least-privilege policy template.\n4. Pause until the user confirms that permission was granted before retrying.\n\n## Parameter Confirmation\n\nConfirm user-customizable values before executing a cloud request. Reuse explicit values already supplied by the user; do not ask again.\n\n| Parameter | Required for | Rule |\n| --- | --- | --- |\n| `--region` | All operations when the configured region is not explicitly accepted | Dataset and AgentSpace must be in this region. |\n| `--agent-space` | All commands | Confirm the exact AgentSpace name. |\n| `--dataset-name` | All Dataset commands in this skill | Use 4-63 ASCII characters matching `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`; do not use uppercase letters, hyphens, spaces, or leading, trailing, or consecutive underscores. |\n| `--description` | Optional create/update description | Keep the UTF-8 encoded value at 255 bytes or fewer. |\n| `--schema` | Create; optional update | Confirm field names, types, Chinese tokenization, JSON keys, and embedding use. The only supported public embedding model value is `agentloop-embedding-v4`. |\n| `--data-array` | Structured writes | Confirm the rows or the source from which they are constructed. |\n| `--query` | `execute-query` | This Skill permits only read-only SELECT or SearchExpr query text. The public API accepts one raw query string and exposes no bind-parameter option; the default query-text cap is 10 MiB. |\n| `--from`, `--to` | Optional SELECT time window | Use non-negative Unix seconds over `__time__`; `to` is exclusive and, when both are non-zero, `from` must be less than `to`. |\n| `--offset`, `--length` | Optional SELECT result window | Use non-negative integers only for SELECT; `length` cannot exceed the configured SELECT maximum, which defaults to 100,000. |\n| `--max-output-length` | Optional SELECT truncation | `0` or omitted returns full values. |\n| `--biz-version` | Optional SELECT against an existing snapshot | This CLI flag serializes to the request-body field `version`; confirm the exact version and omit it for current data. |\n| `--client-token` | Optional create/update/write idempotency | Generate one non-secret UUID and reuse it for retries of the same logical request. `delete-dataset` does not accept this flag. |\n\n## Observability\n\nBefore generating the User-Agent or issuing any cloud request, apply the root [skill version gate](../../SKILL.md#shared-conventions): read `references/manifest.json`, require its non-empty string `version`, and stop on any read or validation failure. Use that exact value as `SKILL_VERSION`; never infer a fallback.\n\nGenerate one session ID before the first AgentLoop API request in a skill session. Generate it once, require exactly 32 lowercase hexadecimal characters, and reuse it for the entire session:\n\n```bash\nSKILL_VERSION=\"{version}\"\nSESSION_ID=\"$(openssl rand -hex 16)\"\nUSER_AGENT=\"AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/skill-version/${SKILL_VERSION}/${SESSION_ID}\"\n```\n\nThe canonical CLI template is:\n\n```bash\n--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/skill-version/{version}/{session-id}\"\n```\n\nObservability rules:\n\n- Append `--user-agent \"${USER_AGENT}\"` to every `aliyun agentloop` invocation, including dry runs, retries, mutations, and verification calls. Command examples omit this repeated global flag for readability; add it before execution.\n- Never generate a new session ID for an individual command or retry.\n- If one workflow also uses an Alibaba Cloud SDK or Terraform, propagate the same session ID through that client's custom user-agent mechanism. Keep one session ID across CLI, SDK, and Terraform calls in the same session.\n- Treat the session ID as non-secret correlation metadata. Do not substitute a request ID, account ID, AccessKey ID, or client token.\n- Do not mutate global Aliyun CLI configuration to set the user agent; pass the session-scoped user agent explicitly on each request.\n\n## Core Workflow\n\nExecute the workflow:\n\n1. Classify the intent: Dataset management, schema change, structured write, read-only SQL/search, deletion, Pipeline materialization, or verification.\n2. Confirm the target region, AgentSpace, Dataset, and operation-specific inputs.\n3. Run CLI, plugin, and credential checks. Stop if any prerequisite fails.\n4. Read the relevant reference:\n   - Dataset lifecycle, schemas, and deletion: `references/dataset/dataset-management.md`\n   - Structured writes and data mutations: `references/dataset/data-operations.md`\n   - Search and SELECT syntax: `references/dataset/query-syntax.md`\n   - Logstore-to-Dataset materialization: finish Dataset schema confirmation, then dispatch to `references/pipeline/pipeline.md` for preview/create/run and return here for Dataset readback.\n5. For complex JSON, run the same command with `--cli-dry-run` first and inspect the serialized URL, query parameters, and body. If the payload contains real conversations or other sensitive values, dry-run the same structure with synthetic values instead of printing the real payload.\n6. Execute the approved command.\n7. Verify the result using `references/dataset/verification-method.md`.\n8. Report the request ID and verification evidence without exposing credentials or secret values.\n\n## Dataset and Schema Rules\n\n- Treat Dataset names as unique within the target AgentSpace. A duplicate create is rejected.\n- Respect the AgentSpace Dataset quota. The service fallback is 100 Datasets per AgentSpace, but the AgentSpace may supply a different quota.\n- Keep create/update request bodies at 1 MiB or less.\n- Require a non-empty schema.\n- Use only `text`, `long`, `double`, and `json` field types.\n- Use `chn` for text tokenization. It has no useful effect on non-text fields.\n- Use `embedding` only on `text` or `json` fields. When present, its value must be exactly `agentloop-embedding-v4`; do not use an internal backend model name or invent another alias.\n- Use `jsonKeys` only under a top-level `json` field. Each indexed child uses `type` and optional `chn`; do not add child `embedding` or another `jsonKeys` level unless current CLI help explicitly exposes those fields.\n- Keep each top-level field name non-empty and at 50 UTF-8 bytes or fewer. The backend does not impose the Dataset-name pattern on fields, but prefer `lower_snake_case` to simplify SQL and case-insensitive structured writes.\n- Never define reserved fields: `id`, `__time__`, `__dataset_seq`, `__effective_seq`, or `__expired_seq`.\n- Keep the effective column budget within 300: three service columns plus one per top-level field plus one per generated embedding column.\n- Treat schema updates as add-only. Omitted existing fields remain; changing or removing an existing definition is rejected. Fetch the current schema before constructing an update.\n- Freeze the consumer field contract before a bulk import. A normalized `question` field must not silently replace required raw `input`, raw `output`, or stable lineage fields.\n- Adding a field does not backfill existing rows. When a populated Dataset has the wrong structural contract, default to a versioned Dataset and Pipeline, reconcile it against the source, switch consumers after verification, and retain the old version until cleanup is explicitly authorized.\n\n## Structured Write Rules\n\nPrefer `add-dataset-data` for row appends. It avoids SQL quoting errors and validates values against the Dataset schema.\n\n- `dataArray` must be non-empty and every entry must be an object.\n- Build rows from the user's authorized field contract, then check those fields against the current schema. An additional field in the schema does not authorize populating it. Preserve requested nesting; for example, a marker requested inside `agentloop_annotations` stays there and must not also become a top-level `marker_id` for easier queries. See `references/dataset/data-operations.md` for the pre-write check.\n- Field matching is case-insensitive, but do not send duplicate case variants.\n- Unknown fields fail the request; omitted schema fields become `null`.\n- `text` values must be strings, `long` values integers, `double` values finite numbers, and `json` values valid JSON.\n- Omit `id` to generate one. If supplied, it must be a UUID string.\n- Omit `__time__` to use the current time. If supplied, it must be a non-null, non-negative Unix timestamp in seconds.\n- Never send `__dataset_seq`.\n- One request is atomic: either all rows commit or none do. The request-body limit is 100 MiB; there is no separate fixed row-count limit for `add-dataset-data`.\n\n## Destructive Operations\n\n`delete-dataset` is the only destructive command in this domain. It removes the Dataset and every row in it, cannot be undone, and has no soft-delete window. There is also no per-row delete command, so a request to \"clean up the test rows\" resolves to deleting the whole Dataset; say that plainly instead of quietly deleting more than the user pictured.\n\n- Never delete without showing `get-dataset` output and the row count first, and never treat an earlier approval for one Dataset as approval for another.\n- Delete exactly one named Dataset per command. Do not iterate over `list-datasets` output, even when the user asks for a bulk cleanup; confirm each target separately.\n- Check whether a Pipeline sinks into the Dataset or an evaluation task reads it, and report what will break before deleting.\n- Do not propose delete-then-recreate as a way to change a field type without stating that all rows are lost.\n\nThe full protocol and the measured command surface are in `references/dataset/dataset-management.md`.\n\n## Query Safety\n\n- Always pass `--type SQL`; it is the only supported statement type.\n- This Skill uses `execute-query` only for read-only SELECT or SearchExpr queries. Never send INSERT, UPDATE, DELETE, DDL, or multiple statements through this command.\n- The public `execute-query` contract carries raw query text and has no bind-parameter field. Do not compose SQL from untrusted text; use `add-dataset-data` for user-provided values whenever it can express the write.\n- The `agentloop:ExecuteQuery` RAM action is not statement-level read-only. This Skill's SELECT-only boundary is an instruction, not a service-side control.\n- Keep the `execute-query` body within the default 100 MiB cap and the query text within the default 10 MiB cap.\n- Use single-dataset statements. Do not assume cross-Dataset queries or joins are supported.\n- Prefer explicit columns and explicit result limits. A SELECT without a limit defaults to 1,000 rows; the configured maximum defaults to 100,000 for SQL `LIMIT` and `--length`.\n- Use `columns` with each `rows` entry by position; the response is row-based, not an array of objects.\n- Use `semantic_distance(field, 'query', 'l2')` with an explicit distance type. The field must have embedding enabled.\n- Keep SearchExpr `similarity()` thresholds in `[0, 1]` and `topk()` values as integers from 1 through 100,000.\n- Do not insert user-provided values into SQL. Use `add-dataset-data` for writes.\n\n## Command Index\n\nAll public Dataset CLI commands, parameters, and help checks are in `references/dataset/related-commands.md`.\n\n## Common Mistakes\n\n| Wrong | Right | Reason |\n| --- | --- | --- |\n| `aliyun cms ... dataset ...` | `aliyun agentloop ...` | This skill uses the AgentLoop 2026-05-20 public API. |\n| `--type sql` without checking | `--type SQL` | The service currently requires `SQL`. |\n| Create with an empty schema | Supply at least one typed field | Empty schemas are rejected. |\n| Update an existing field type | Add a new top-level field or update description | Schema evolution is add-only. |\n| Put JSON in a `text` field | Declare/use a `json` field | Structured writes validate field types. |\n| Expect `response.data` | Zip `columns` with each entry in `rows` | Query responses are row-based. |\n| Use `execute-query` for a data mutation | Use `add-dataset-data` for row appends | This Skill permits `execute-query` only for read-only queries. |\n| `semantic_distance(field, 'q')` | `semantic_distance(field, 'q', 'l2')` | Current Dataset execution requires an explicit distance type. |\n| `--version v1` | `--biz-version v1` | Global `--version` selects the OpenAPI version; the Dataset snapshot selector is `--biz-version`. |\n| Reuse a new client token on retry | Reuse the original token for the same logical request | Idempotency depends on a stable token. |\n| `delete-dataset ... --client-token <uuid>` | Omit the flag; re-check with `get-dataset` instead | `delete-dataset` accepts no client token, so a retry is not idempotent-by-token. |\n| Delete a Dataset to remove a few test rows | Say that no per-row delete exists and confirm the whole-Dataset scope | Deletion is all-or-nothing and irreversible. |\n| `--dataset-name my-dataset` | `--dataset-name my_dataset` | Dataset names reject hyphens; only underscores separate words. |\n| Keep only a derived `question` in trace-derived data | Preserve required raw `input`, `output`, and lineage beside derived fields | Derived text cannot prove source preservation or support later reprocessing. |\n| Add omitted fields to populated v1 and rerun into it | Create and verify a versioned Dataset/Pipeline | Add-only schema does not backfill and reruns can duplicate rows. |\n| Accept a Pipeline import from row count alone | Reconcile required fields, lineage, empties, duplicates, and transforms | Transport success can still violate the data contract. |\n\n## References\n\n| File | Use |\n| --- | --- |\n| `references/dataset/dataset-management.md` | Create, list, get, update, delete, and schema construction. |\n| `references/dataset/data-operations.md` | Structured row append and typed values. |\n| `references/dataset/query-syntax.md` | Read-only SQL, SearchExpr, semantic retrieval, windows, and response shape. |\n| `references/dataset/related-commands.md` | Supported command and parameter inventory. |\n| `references/dataset/verification-method.md` | Dry-run and post-operation verification. |\n| `references/dataset/ram-policies.md` | RAM actions, resource ARN, and policy examples. |\n| `references/pipeline/pipeline.md` | Logstore-to-Dataset processing and execution workflow. |\n\nFile v0.1.5:references/dataset/query-syntax.md\n\n# Dataset Query Syntax\n\nAll query modes use `execute-query` with `--type SQL`. The service detects SQL, SearchExpr, or SearchExpr piped into SQL.\n\n## Backend-Enforced Limits\n\n| Input or operation | Constraint |\n| --- | --- |\n| Request body | Default cap: 100 MiB. |\n| Query text | Default cap: 10 MiB. |\n| SELECT without a limit | Defaults to 1,000 rows. |\n| SQL `LIMIT` | Non-negative integer, maximum 100,000 by default; `LIMIT ALL` is unsupported. |\n| `--offset` / `--length` | Non-negative; `length` has the same configured maximum as SQL `LIMIT`, 100,000 by default. |\n| `--from` / `--to` | Non-negative Unix seconds; when both are non-zero, `from < to`; `to` remains exclusive. |\n| `--max-output-length` | Non-negative; `0` or omission returns full values. |\n| SearchExpr `similarity()` | Threshold in `[0, 1]`, using `<`, `<=`, `>`, or `>=`. |\n| SearchExpr `topk()` | Integer from 1 through 100,000, using `<` or `<=`. |\n\nTreat the request-body, query-text, default SELECT, and maximum SELECT values as service defaults that deployments can configure downward or upward. Use the values reported by an API error when they differ.\n\n## Response Shape\n\nSuccessful queries return:\n\n```json\n{\n  \"requestId\": \"<request_id>\",\n  \"meta\": {\n    \"affectedRows\": 0,\n    \"elapsedMillisecond\": 12,\n    \"progress\": \"Complete\",\n    \"count\": 2\n  },\n  \"columns\": [\"id\", \"question\", \"score\"],\n  \"columnTypes\": [\"text\", \"text\", \"double\"],\n  \"rows\": [\n    [\"<uuid_1>\", \"How?\", 0.95],\n    [\"<uuid_2>\", \"Why?\", 0.91]\n  ]\n}\n```\n\nInterpret `rows[i][j]` with `columns[j]`. Do not expect a `data` object array.\n\n## SQL SELECT\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"SELECT id, __time__, question, score FROM <dataset_name> WHERE score >= 0.8 ORDER BY score DESC LIMIT 20\"\n```\n\nUse only the target Dataset. Prefer explicit columns and LIMIT. `SELECT *` expands to `id`, `__time__`, and public schema fields without exposing physical embedding columns.\n\n## Result and Time Windows\n\nUse request parameters rather than rewriting a SELECT when the user wants an external result window:\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"SELECT id, question FROM <dataset_name> ORDER BY __time__ DESC\" \\\n  --from <inclusive_unix_seconds> \\\n  --to <exclusive_unix_seconds> \\\n  --offset 0 \\\n  --length 20 \\\n  --max-output-length 4096\n```\n\n- `from` and `to` filter the `__time__` system field. Zero or omission means no corresponding bound; negative values are rejected, and non-zero bounds must satisfy `from < to`.\n- `offset` and `length` apply only to top-level SELECT results and must be non-negative. `length` cannot exceed the configured SELECT maximum, which defaults to 100,000.\n- `max-output-length` truncates long text/JSON output values and reports truncation metadata. Omit it or pass `0` for full values.\n- `--biz-version <version>` reads an existing immutable Dataset snapshot and serializes to the request-body field `version`. Do not use the global `--version` flag for a Dataset snapshot. Omit `--biz-version` for current data. The AgentLoop CLI 0.7.1 does not expose snapshot create/list/delete commands.\n\n## SearchExpr\n\nSearchExpr supports field comparisons, boolean logic, parentheses, and field-value sugar:\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"question:error AND score >= 0.8\"\n```\n\nSupported forms include:\n\n- Comparisons: `=`, `!=`, `>`, `>=`, `<`, `<=`\n- Boolean logic: `AND`, `OR`, `NOT`, and parentheses\n- Exact value: `field:value`, `field:'value'`, or `field:\"value\"`\n- Existence: `field:*`\n- Prefix: `field:prefix*`\n\nDo not use fieldless terms, `IN`, `BETWEEN`, `LIKE`, `IS NULL`, arbitrary functions, subqueries, or a JSON filter DSL on the SearchExpr side.\n\n## Semantic SearchExpr\n\nThe target field must have `embedding` enabled. Keep `similarity()` thresholds in `[0, 1]`. Keep `topk()` thresholds integral and between 1 and 100,000.\n\n```bash\n# Distance threshold: smaller values are closer.\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"similarity(question, '<semantic_query>') < 0.3\"\n\n# Top-K semantic retrieval.\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"topk(question, '<semantic_query>') <= 10\"\n```\n\nCombine `similarity()` or `topk()` with other SearchExpr conditions using `AND`, not `OR`.\n\n## Search Pipe SQL\n\nPlace SearchExpr on the left of a top-level pipe and a SELECT on the right:\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"question:error AND score >= 0.8 | SELECT id, question, score FROM <dataset_name> ORDER BY score DESC LIMIT 10\"\n```\n\nThe SQL side of a pipe must be SELECT.\n\n## SQL Semantic Distance\n\nUse an explicit distance type with current Dataset execution:\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"SELECT id, question, semantic_distance(question, '<semantic_query>', 'l2') AS distance FROM <dataset_name> ORDER BY distance ASC LIMIT 10\"\n```\n\nAccepted distance families are:\n\n- `l2`, `euclidean`, or `distance`\n- `cosine`, `cos`, or `similarity`\n- `ip`, `dot`, or `inner_product`\n\nUse `l2` unless the user explicitly chooses another supported distance meaning.\n\n## Read-only SQL Scope\n\nThis Skill sends only SELECT or SearchExpr queries through `execute-query`. The public request supplies raw query text and `ExecuteQuery` authorization is not statement-level read-only, so do not rely on RAM or the CLI to block a mutation.\n\n- No JOIN or cross-Dataset access.\n- No UNION, INTERSECT, or EXCEPT.\n- Use explicit columns and a bounded LIMIT.\n- Build query text only from documented read-only patterns and confirmed Dataset schema fields. Do not accept a user-supplied SQL template or add user-provided text to the statement.\n\nFile v0.1.5:references/dataset/ram-policies.md\n\n# RAM Policies\n\n## Required Actions\n\n| API | RAM action |\n| --- | --- |\n| CreateDataset | `agentloop:CreateDataset` |\n| ListDatasets | `agentloop:ListDatasets` |\n| GetDataset | `agentloop:GetDataset` |\n| UpdateDataset | `agentloop:UpdateDataset` |\n| DeleteDataset | `agentloop:DeleteDataset` |\n| AddDatasetData | `agentloop:AddDatasetData` |\n| ExecuteQuery | `agentloop:ExecuteQuery` |\n\nDataset resource ARN:\n\n```text\nacs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/<dataset_name>\n```\n\n`ListDatasets` uses the Dataset wildcard under one AgentSpace:\n\n```text\nacs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/*\n```\n\n## Least-Privilege Template\n\nReplace all placeholders. Split read and write permissions when the identity does not need mutations.\n\nThis template deliberately omits `agentloop:DeleteDataset`. Grant it only to an identity that is expected to destroy Datasets, and prefer scoping it to a single named Dataset ARN rather than the wildcard.\n\n```json\n{\n  \"Version\": \"1\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"agentloop:CreateDataset\",\n        \"agentloop:ListDatasets\",\n        \"agentloop:GetDataset\",\n        \"agentloop:UpdateDataset\",\n        \"agentloop:AddDatasetData\",\n        \"agentloop:ExecuteQuery\"\n      ],\n      \"Resource\": \"acs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/*\"\n    }\n  ]\n}\n```\n\nFor a single existing Dataset, narrow applicable actions to:\n\n```text\nacs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/<dataset_name>\n```\n\nKeep `ListDatasets` on the wildcard resource if listing is required. Confirm whether CreateDataset authorization needs the future Dataset ARN with the requested name in the target account.\n\n## Delete-Capable Template\n\nAdd this statement only when deletion is an intended capability for the identity. `DeleteDataset` destroys the Dataset and all of its rows and cannot be undone, so bind it to the specific Dataset name instead of the wildcard whenever the target is known.\n\n```json\n{\n  \"Version\": \"1\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"agentloop:GetDataset\",\n        \"agentloop:DeleteDataset\"\n      ],\n      \"Resource\": \"acs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/<dataset_name>\"\n    }\n  ]\n}\n```\n\n`GetDataset` is included because the confirmation protocol requires showing the user what will be destroyed before deleting it.\n\n## Query-Capable Template\n\n```json\n{\n  \"Version\": \"1\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"agentloop:ListDatasets\",\n        \"agentloop:GetDataset\",\n        \"agentloop:ExecuteQuery\"\n      ],\n      \"Resource\": \"acs:agentloop:<region_id>:<account_id>:agentspace/<agent_space_name>/dataset/*\"\n    }\n  ]\n}\n```\n\n`ExecuteQuery` can execute mutations as well as reads. The RAM action has no statement-type condition, so a policy that grants it cannot enforce read-only SQL. Do not include `ExecuteQuery` in a security boundary that must prevent writes unless a more restrictive policy mechanism is available for that account.\n\n## Permission Failure Handling\n\n1. Record the API action, denied action, HTTP status, and request ID.\n2. Do not print request signing material or credentials.\n3. Compare the denied action with the tables above.\n4. Invoke `ram-permission-diagnose` if installed. Otherwise present the smallest required action and scoped resource ARN.\n5. Ask the user to attach the approved policy through the Alibaba Cloud RAM console.\n6. Wait for confirmation before retrying.\n\nFile v0.1.5:references/dataset/related-commands.md\n\n# Related CLI Commands\n\nThe AgentLoop plugin fixes the API version at `2026-05-20`; do not add a CMS product or a different API version.\n\n| Area | Command | Purpose | Help validation |\n| --- | --- | --- | --- |\n| Dataset | `aliyun agentloop create-dataset` | Create a Dataset and schema. | `aliyun agentloop create-dataset --help` |\n| Dataset | `aliyun agentloop list-datasets` | List and filter Datasets. | `aliyun agentloop list-datasets --help` |\n| Dataset | `aliyun agentloop get-dataset` | Get one Dataset and its schema. | `aliyun agentloop get-dataset --help` |\n| Dataset | `aliyun agentloop update-dataset` | Update description or add schema fields. | `aliyun agentloop update-dataset --help` |\n| Dataset | `aliyun agentloop delete-dataset` | Delete a Dataset and all its rows. Destructive and irreversible. | `aliyun agentloop delete-dataset --help` |\n| Data | `aliyun agentloop add-dataset-data` | Append structured rows atomically. | `aliyun agentloop add-dataset-data --help` |\n| Data | `aliyun agentloop execute-query` | Execute read-only SQL, SearchExpr, or pipe queries. | `aliyun agentloop execute-query --help` |\n\n## Parameter Inventory\n\n| Command | Required | Optional |\n| --- | --- | --- |\n| `create-dataset` | `--agent-space`, `--dataset-name`, `--schema` | `--description`, `--client-token`, `--region` |\n| `list-datasets` | `--agent-space` | `--dataset-name`, `--max-results`, `--next-token`, `--region` |\n| `get-dataset` | `--agent-space`, `--dataset-name` | `--region` |\n| `update-dataset` | `--agent-space`, `--dataset-name` | `--description`, `--schema`, `--client-token`, `--region` |\n| `delete-dataset` | `--agent-space`, `--dataset-name` | `--region` (no `--client-token`) |\n| `add-dataset-data` | `--agent-space`, `--dataset-name`, `--data-array` | `--client-token`, `--region` |\n| `execute-query` | `--agent-space`, `--dataset-name`, `--type`, `--query` | `--from`, `--to`, `--offset`, `--length`, `--max-output-length`, `--biz-version`, `--region` |\n\nUse `--cli-dry-run` for request inspection, `--cli-query <jmespath>` for output filtering, and `--pager` for supported pageable APIs.\n\n## Published Surface Note\n\nThe current public `aliyun-cli-agentloop 0.7.1` command surface does not expose create/list/delete version commands. Do not invent CLI subcommands for them. `execute-query --biz-version` may read an already existing snapshot version; the CLI serializes this flag as the request-body field `version`.\n\nFile v0.1.5:references/dataset/verification-method.md\n\n# Verification Method\n\n## 1. Local Prerequisites\n\n```bash\naliyun version\naliyun plugin show --name agentloop\naliyun configure list\n```\n\nExpected:\n\n- Aliyun CLI is 3.3.15 or later.\n- `aliyun-cli-agentloop` is 0.7.1 or later and supports API `2026-05-20`.\n- A usable profile/identity and intended region are shown without exposing credentials.\n\n## 2. Command Surface\n\nBefore using an unfamiliar parameter, confirm it appears in help:\n\n```bash\naliyun agentloop <subcommand> --help\n```\n\nValidate these six public Dataset subcommands: `create-dataset`, `list-datasets`, `get-dataset`, `update-dataset`, `add-dataset-data`, and `execute-query`. Do not infer unpublished version-management commands.\n\n## 3. Dry Run\n\nAppend `--cli-dry-run` to complex JSON, writes, updates, or queries. For real conversations or sensitive data, dry-run an equivalent synthetic payload instead of exposing the real body.\n\nInspect:\n\n- `Endpoint` matches `agentloop.<region>.aliyuncs.com` or the explicitly approved endpoint.\n- `API Version` is `2026-05-20`.\n- `API Action` matches the intended operation.\n- The URL contains the exact AgentSpace and Dataset.\n- Row keys and nesting match the user-authorized payload, including marker placement; a schema-valid extra field is still an unrequested change.\n- JSON numbers, booleans, arrays, objects, and null values keep their types.\n- A retry uses the same `clientToken` as the original logical request.\n\nDry run validates serialization only. It does not validate that the resource exists, the identity is authorized, embedding generation can execute, or the SQL can execute.\n\n## 4. Dataset Verification\n\nAfter create or update:\n\n```bash\naliyun agentloop get-dataset \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name>\n```\n\nExpected:\n\n- `datasetName` and `agentSpace` match.\n- `schema` contains the requested fields and types.\n- `description` reflects the requested value.\n- `requestId` is present.\n\nFor list pagination, verify the requested filter, page size, and `nextToken`; pass the returned token unchanged to the next request.\n\n## 5. Structured Write Verification\n\nCheck `affectedRows` equals the number of submitted rows. Then issue a narrow SELECT using a stable supplied `id` or another unique value:\n\n```bash\naliyun agentloop execute-query \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --type SQL \\\n  --query \"SELECT id, __time__, <fields> FROM <dataset_name> WHERE id = '<row_uuid>' LIMIT 1\"\n```\n\nIf IDs were generated by the service, query the newly written records using a narrow unique predicate and time window.\n\nHonor a user-specified readback predicate. A nested marker may be inspected in returned JSON without becoming a filter column. Never add a top-level marker, populate another optional schema field, or modify the schema merely to simplify this query. If the returned rows cannot uniquely establish the requested write, report that verification limit rather than expanding the payload or claiming proof.\n\n## 6. Query Verification\n\nExpected for SELECT/search:\n\n- `meta.progress` is `Complete`.\n- `meta.count` equals the number of returned rows.\n- `columns` and `columnTypes` have matching lengths.\n- Every row has the same number of entries as `columns`.\n- If `maxOutputLength` was used, inspect `meta.truncation` before treating values as complete.\n\n## 7. Observability Verification\n\nConfirm that every `aliyun agentloop` invocation, including dry runs and verification calls, used the same session-scoped user agent:\n\n```bash\n--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/skill-version/${SKILL_VERSION}/${SESSION_ID}\"\n```\n\n`SESSION_ID` must be the single 32-character lowercase hexadecimal value generated once for this skill session. Do not regenerate it for retries or mutate global Aliyun CLI configuration to set the user agent.\n\n## 8. Pipeline and Migration Verification\n\nFor Logstore-to-Dataset imports, do not stop at Pipeline `Succeeded`, `affectedRows`, or a narrow happy-path sample. Follow `references/pipeline/verification-method.md` and verify:\n\n- the target schema contains every raw, derived, and lineage field required by consumers;\n- source and target counts reconcile after declared filters;\n- no source-nonempty required value became target-empty;\n- no unexplained missing, extra, or duplicate lineage IDs exist;\n- derived fields have no transform failures or wrapper residue;\n- query output is not truncated;\n- downstream Evaluation/Experiment variable mapping can read the required columns.\n\nIf a populated Dataset has the wrong structural contract, verify a versioned replacement against the original source. Adding fields in place does not backfill old rows, and a rerun can create duplicates.\n\nFile v0.1.5:references/evaluation/acceptance-criteria.md\n\n# Acceptance Criteria: alibabacloud-agentloop-management (evaluation domain)\n\n**Scenario**: AgentLoop evaluation workflow orchestration\n**Purpose**: Skill testing acceptance criteria\n\n---\n\n# Correct CLI Command Patterns\n\n## 1. Product - verify product name exists\n\n#### [OK] CORRECT\n```bash\naliyun agentloop list-evaluators --agent-space <space>\n```\n\n#### [NO] INCORRECT\n```bash\naliyun AgentLoop ListEvaluators --agent-space <space>   # Wrong: API mode, not plugin mode\naliyun agentloop listevaluators --agent-space <space>   # Wrong: missing hyphen\n```\n\n## 2. Command - verify action exists under the product\n\n#### [OK] CORRECT\n```bash\naliyun agentloop create-evaluation-task --agent-space <space> --task-name <name> --task-mode batch --data-type trace --data-filter '{}' --evaluators '[]'\n```\n\n#### [NO] INCORRECT\n```bash\naliyun agentloop CreateEvaluationTask ...   # Wrong: PascalCase, not plugin mode\naliyun agentloop create-evaluation-task ...  # Correct format (for reference)\n```\n\n## 3. Parameters - verify each parameter name exists\n\n#### [OK] CORRECT\n```bash\naliyun agentloop get-evaluator --agent-space <space> --name <evaluator-name> --biz-version v1\n```\n\n#### [NO] INCORRECT\n```bash\naliyun agentloop get-evaluator --agentspace <space> ...      # Wrong: missing hyphen\naliyun agentloop get-evaluator --agent-space <space> --version v1  # Wrong: should be --biz-version\n```\n\n## 4. JSON parameters - use compact JSON for complex flags\n\n#### [OK] CORRECT\n```bash\naliyun agentloop create-evaluation-task \\\n  --data-filter '{\"maxRecords\":100}' \\\n  --evaluators '[{\"evaluatorRef\":\"Builtin.agent_correctness\"}]'\n```\n\n#### [NO] INCORRECT\n```bash\naliyun agentloop create-evaluation-task \\\n  --data-filter maxRecords=100 \\          # Wrong: must be JSON\n  --evaluators Builtin.agent_correctness   # Wrong: must be JSON array\n```\n\n## 5. Batch bounds - never invent the window or the record cap\n\nA batch task decides how much customer data gets scanned and billed, so its bounds are the user's call. When the request does not carry both a timezone-bearing time window and `dataFilter.maxRecords`, stop and ask for the missing values before building the spec, and say why a batch task must be bounded. Reusing a window from other tasks in the same AgentSpace, or falling back to a default range such as the last 7 days, is not consent.\n\n#### [OK] CORRECT\n\nAsk first, then build the spec from the values the user supplies:\n\n```text\nYour batch trace evaluation still needs two bounds I should not pick for you:\n  - a time window (start and end, with timezone)\n  - dataFilter.maxRecords\nBatch tasks scan and bill by volume, so an unbounded run can read far more than you expect.\n```\n\n#### [NO] INCORRECT\n```bash\naliyun agentloop create-evaluation-task \n  --data-filter '{\"maxRecords\":1000}'             # Wrong: cap chosen for the user\n  --from 2026-07-16T00:00:00+08:00                 # Wrong: window copied from other tasks\n  --to 2026-08-17T00:00:00+08:00\n\npython3 scripts/evaluation/agentloop_eval.py run --spec evaluation.json --execute --allow-unbounded\n# Wrong: bypassing the missing cap instead of asking, and executing without authorization\n```\n\n# Correct Python Wrapper Patterns\n\n## 1. Spec file loading - must be a JSON object\n\n#### [OK] CORRECT\n```python\nspec = {\n    \"agent_space\": \"my-space\",\n    \"region\": \"cn-hangzhou\",\n    \"task\": {\n        \"mode\": \"oneshot\",\n        \"data_filter\": {\"provided\": {\"input\": \"hello\"}},\n        \"evaluator_refs\": [{\"ref\": \"Builtin.agent_correctness\"}]\n    }\n}\n```\n\n#### [NO] INCORRECT\n```python\nspec = {\n    \"agentSpace\": \"my-space\",  # Wrong: use snake_case in spec, wrapper converts\n    \"task\": \"oneshot\"          # Wrong: task must be an object\n}\n```\n\n## 2. Evaluator type - create as AGENT or CODE only\n\n#### [OK] CORRECT\n```python\n# Genuine StarOps Agent evaluator (standard digital-employee mode): omit agentEvaluatorMode\n{\"action\": \"create\", \"name\": \"my-agent-eval\", \"type\": \"AGENT\", \"metric_name\": \"quality\", \"biz_version\": \"v1\", \"config\": {\"prompt\": \"Judge {{input}}\"}}\n# LLM-style evaluator (LLM-as-judge): AGENT plus agentEvaluatorMode=raw_prompt\n{\"action\": \"create\", \"name\": \"my-llm-style-eval\", \"type\": \"AGENT\", \"metric_name\": \"quality\", \"biz_version\": \"v1\", \"config\": {\"agentEvaluatorMode\": \"raw_prompt\", \"prompt\": \"Judge {{input}}\"}}\n{\"action\": \"create\", \"name\": \"my-code-eval\", \"type\": \"CODE\", \"metric_name\": \"quality\", \"biz_version\": \"v1\"}\n```\n\n#### [NO] INCORRECT\n```python\n{\"action\": \"create\", \"type\": \"agent\", ...}    # Wrong: must be uppercase\n{\"action\": \"create\", \"type\": \"LLM\", ...}      # Wrong for new specs: use AGENT + agentEvaluatorMode=raw_prompt instead\n{\"action\": \"create\", \"type\": \"CUSTOM\", ...}   # Wrong: not a supported type\n{\"action\": \"create\", \"type\": \"AGENT\", \"config\": {\"rawPromptBackend\": \"direct_llm\", ...}}  # Wrong: rawPromptBackend is no longer part of the contract and is stripped\n```\n\n## 3. Custom output fields - use config.outputSchema\n\n#### [OK] CORRECT\n```python\n{\"config\": {\"outputSchema\": {\"score\": {\"type\": \"number\", \"required\": True, \"range\": [0, 1]}, \"explanation\": {\"type\": \"string\", \"required\": True}, \"risk_level\": {\"type\": \"enum\", \"required\": False, \"options\": [\"low\", \"medium\", \"high\"]}}}}\n{\"config\": {\"outputSchema\": {\"risk_level\": {\"type\": \"enum\", \"options\": [\"low\", \"medium\", \"high\"]}}}}  # Wrapper defaults score/explanation\n```\n\n#### [NO] INCORRECT\n```python\n{\"config\": {\"customFields\": {\"risk_level\": \"enum\"}}}  # Wrong: custom result fields belong in outputSchema\n```\n\n## 4. Dataset config - must use exact camelCase keys\n\n#### [OK] CORRECT\n```python\n{\"data_type\": \"dataset\", \"config\": {\"datasetName\": \"my-dataset\"}}\n```\n\n#### [NO] INCORRECT\n```python\n{\"data_type\": \"dataset\", \"config\": {\"dataset_name\": \"my-dataset\"}}  # Wrong: snake_case not converted in config\n```\n\n## 5. Time window - must include timezone\n\n#### [OK] CORRECT\n```python\n{\"window\": {\"start\": \"2026-07-14T09:00:00+08:00\", \"end\": \"2026-07-14T10:00:00+08:00\"}}\n```\n\n#### [NO] INCORRECT\n```python\n{\"window\": {\"start\": \"2026-07-14T09:00:00\", \"end\": \"2026-07-14T10:00:00\"}}  # Wrong: no timezone\n```\n\n## 6. Continuous evaluation - requires explicit flag\n\n#### [OK] CORRECT\n```bash\npython3 scripts/evaluation/agentloop_eval.py run --spec continuous.json --allow-continuous --execute\n```\n\n#### [NO] INCORRECT\n```bash\npython3 scripts/evaluation/agentloop_eval.py run --spec continuous.json --execute\n# Error: continuous evaluation requires --allow-continuous after explicit cost approval\n```\n\nArchive v0.1.6: 86 files, 310805 bytes\n\nFiles: references/ai.md (15677b), references/apm.md (47049b), references/dataset/data-operations.md (5438b), references/dataset/dataset-management.md (8048b), references/dataset/dataset.md (17662b), references/dataset/query-syntax.md (6376b), references/dataset/ram-policies.md (3619b), references/dataset/related-commands.md (2445b), references/dataset/verification-method.md (4789b), references/evaluation/acceptance-criteria.md (6462b), references/evaluation/api-map.md (8182b), references/evaluation/cli-installation-guide.md (2153b), references/evaluation/evaluation.md (22736b), references/evaluation/examples/batch-dataset-example.json (838b), references/evaluation/examples/batch-trace-example.json (846b), references/evaluation/examples/oneshot-example.json (694b), references/evaluation/ram-policies.md (3775b), references/evaluation/related-commands.md (3320b), references/evaluation/result-analysis.md (3284b), references/evaluation/spec-format.md (9472b), references/evaluation/verification-method.md (2725b), references/instrumentation/instrumentation.md (14020b), references/instrumentation/sources.md (7807b), references/live-debug-ram-policies.md (5949b), references/live-debug-runtime.md (13604b), references/live-debug.md (41973b), references/manifest.json (19b), references/onboarding.md (11933b), references/pipeline/nodes-and-expressions.md (6054b), references/pipeline/nodes/_TEMPLATE.md (4409b), references/pipeline/nodes/agentic-call.md (9050b), references/pipeline/nodes/dedup-exact.md (6860b), references/pipeline/nodes/dedup-fuzzy.md (6954b), references/pipeline/nodes/dedup-semantic.md (7916b), references/pipeline/nodes/doc-stats.md (5835b), references/pipeline/nodes/embedding.md (5701b), references/pipeline/nodes/extend.md (5030b), references/pipeline/nodes/limit.md (2315b), references/pipeline/nodes/llm-call.md (9240b), references/pipeline/nodes/make-instance.md (22725b), references/pipeline/nodes/OVERVIEW.md (7994b), references/pipeline/nodes/project.md (5044b), references/pipeline/nodes/sample.md (6021b), references/pipeline/nodes/semantic-cluster.md (6576b), references/pipeline/nodes/where.md (4306b), references/pipeline/operators/_TEMPLATE.md (7040b), references/pipeline/operators/agentic-call.md (14634b), references/pipeline/operators/dedup-exact.md (10561b), references/pipeline/operators/dedup-fuzzy.md (12602b), references/pipeline/operators/dedup-semantic.md (13890b), references/pipeline/operators/dedup.md (26673b), references/pipeline/operators/doc-stats.md (7936b), references/pipeline/operators/embedding.md (7615b), references/pipeline/operators/extend.md (4702b), references/pipeline/operators/limit.md (2632b), references/pipeline/operators/llm-call.md (21165b), references/pipeline/operators/make-instance.md (31234b), references/pipeline/operators/OVERVIEW.md (7946b), references/pipeline/operators/project.md (4429b), references/pipeline/operators/sample.md (10556b), references/pipeline/operators/semantic-cluster.md (9519b), references/pipeline/operators/where.md (3779b), references/pipeline/pipeline-cli-map.md (8628b), references/pipeline/pipeline.md (27116b), references/pipeline/ram-policies.md (6044b), references/pipeline/related-commands.md (6384b), references/pipeline/spec-format.md (8479b), references/pipeline/trace/ot-ai-collection-spec.md (39256b), references/pipeline/trace/ot-ai-trace-recipe.md (7427b), references/pipeline/verification-method.md (8535b), references/ram-policies.md (5747b), scripts/evaluation/agentloop_eval.py (51286b), scripts/evaluation/analyze_evaluation_results.py (18496b), scripts/evaluation/requirements.txt (465b), scripts/instrumentation/fetch_docs.py (28806b), scripts/live-debug/common.sh (4937b), scripts/live-debug/delete_all_probes.sh (2514b), scripts/live-debug/delete_task.sh (1422b), scripts/live-debug/get_task.sh (995b), scripts/live-debug/list_tasks.sh (1413b)\n\nFile v0.1.6:SKILL.md\n\n---\nname: alibabacloud-agentloop-management\ndescription: |\n  The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTask dynamic logging, snapshots, metrics, spans, and JVM inspection.\nlicense: Apache-2.0\nmetadata:\n  domain: aiops\n  owner: agentloop\n  contact: agentloop@alibaba-inc.com\n---\n\n# AgentLoop Skill Router\n\n> **Positioning**: This skill is the single entry point for Alibaba Cloud **AgentLoop** requests. It only classifies the user's intent and dispatches to one of the six domain playbooks below. All executable rules - prerequisites, credentials, RAM policies, parameter confirmation, safety protocols, command usage, and verification - live inside the domain files. Do not run any cloud operation before reading the matched domain file.\n\n**Compatibility**: cloud-operation domains require Aliyun CLI 3.3.15 or later; Pipeline requires `aliyun-cli-agentloop` 0.7.4 or later; bundled evaluation, Pipeline, and public-document retrieval scripts require Python 3.8 or later. Instrumentation guidance and public-document retrieval do not require Aliyun CLI, cloud credentials, or a browser.\n\n## Routing Table\n\n| # | Domain | Intent | Entry file (read first) |\n|---|--------|--------|-------------------------|\n| 1 | Application onboarding (APM & AI observability) | Instrument an application so it reports to AgentLoop: probe or agent install, APM onboarding, `aliyun-bootstrap`, `AliyunJavaAgent`, `instgo`, `cms_node_sdk`, `ack-onepilot`, OpenTelemetry, LicenseKey, K8s/ACK/ECS onboarding, LLM and AI-framework tracing (Dify, LangChain, DashScope) | [references/onboarding.md](references/onboarding.md) - internally routes to [references/apm.md](references/apm.md) / [references/ai.md](references/ai.md) |\n| 2 | Evaluation | Score model, agent, or trace quality: create and update evaluators and evaluator skills, one-shot sample tests, batch trace or Dataset evaluation, trace backfill, poll an evaluation task, analyze results and low-score cases | [references/evaluation/evaluation.md](references/evaluation/evaluation.md) |\n| 3 | Dataset | Store and retrieve structured rows: Dataset lifecycle and schema, append rows with `add-dataset-data`, read-only queries with `execute-query`, SQL or SearchExpr, semantic search, embedding fields | [references/dataset/dataset.md](references/dataset/dataset.md) |\n| 4 | Pipeline | Transform source data into a Dataset once or on a schedule: import Logstore/SLS data into a Dataset, import traces, design specs, preview/create/run, inspect runs, control the lifecycle, configure processing nodes, and map OT AI traces | [references/pipeline/pipeline.md](references/pipeline/pipeline.md) |\n| 5 | Live-Debug runtime diagnostics | Diagnose an already-running Java or Python application with CMS ServiceTask: dynamic log/snapshot/metric/span probes, JVM commands (OGNL, decompile, thread/memory/runtime inspection), disable/clear probes, and query capture results through SLS | [references/live-debug-runtime.md](references/live-debug-runtime.md) |\n| 6 | High-code instrumentation | Teach, implement, or troubleshoot manual instrumentation for AgentLoop with loongsuite-genai-utils / language-specific GenAI Utils and OpenTelemetry SDK: Java, Go, Python, Node.js; LLM/Agent/Tool/Retrieval spans, LLM Trace field formats, async/cross-process context propagation, business attributes and broken traces | [references/instrumentation/instrumentation.md](references/instrumentation/instrumentation.md) — dynamically retrieves official documentation without a browser |\n\n## Dispatch Rules\n\n1. Classify the request into one or more domains using the routing table, then read **only** the matched domain entry file(s). Never preload all domains.\n   For high-code/manual instrumentation, GenAI field semantics, or context propagation, dispatch to **High-code instrumentation first**. Only add Application onboarding when cloud setup, endpoint discovery, or service registration is actually needed; code guidance must not be blocked by onboarding's CLI/workspace prerequisites.\n2. Follow the matched domain file completely. Each domain defines its own prerequisites, credentials check, RAM policies, parameter confirmation, execution-safety protocol, and verification method.\n   For Live-Debug, the migrated entry file preserves the original skill contract and is authoritative for that domain wherever its module-specific rules differ from the shared conventions below.\n   For a vague Live-Debug request, apply its parameter-completeness gate immediately after reading the entry file: state which target information is missing and stop. Treat the clarification as a completed final response for this run, not a request for another message. Use only declarative wording such as `Required inputs for a future run: ...`. The response MUST NOT contain a question mark or any request/invitation phrase, including `please provide`, `provide`, `send`, `reply`, `tell me`, `can you`, `could you`, `请提供`, `请补充`, `提供`, `补充`, `告知`, or `回复`. End exactly with `No diagnostic or cloud action was executed; this run is complete.` Do not run prerequisite checks, discover workspaces/services, inspect credentials, create output files, or issue any cloud call until a future request already supplies the required information.\n3. If the request matches none of the domains, state that it is out of scope for this skill and do not dispatch.\n4. If the intent is ambiguous between two domains, ask one clarifying question before dispatching.\n\n### Disambiguating Dataset vs Pipeline vs Evaluation\n\n- Writing or reading rows the user already has: **Dataset**.\n- Deriving new rows from LogStore or trace data through processing nodes: **Pipeline**. Create or confirm the sink Dataset first.\n- Judging the quality of existing traces or Dataset rows with an evaluator: **Evaluation**.\n\n## Delegated Domain: Experience\n\nExperience work - recalling prior experience, similar cases, past incidents and fixes, old runbooks, lessons learned, and the lifecycle of experience stores (ContextStore) and their API Keys - is **not** implemented in this skill. It lives in the separate `alibabacloud-agentloop-experience` skill.\n\nWhen a request needs experience, on its own or as one step of a multi-domain request:\n\n1. Check whether the `alibabacloud-agentloop-experience` skill is available in the current environment.\n2. If it is available, hand the experience part off to it and follow that skill's own rules. Do not reimplement recall or ContextStore commands here.\n3. If it is not available, tell the user that this part requires the separate skill and point them at <https://skills.aliyun.com/skills/alibabacloud-agentloop-experience> to install it. Offer to help with the installation, and wait for the user's answer.\n4. Never guess at experience behavior in place of the missing skill. Continue with the remaining in-scope domains and report the experience step as blocked on that skill.\n\n## Multi-Intent Handling\n\n- Execute multiple domains sequentially in dependency order; finish and verify one mutation stage before starting the next.\n- For Logstore-to-Dataset materialization: confirm or create the Dataset schema, preview the Pipeline, create and observe the Pipeline run, then read back and reconcile Dataset contents. Start Evaluation only after the Dataset field contract passes.\n- When the user also asks to reuse prior work, resolve that experience step through the delegated skill above before the in-scope domains start, and say so if the skill is missing.\n\n## Shared Conventions\n\n- **Skill version gate (before the first cloud call)**: read and parse [references/manifest.json](references/manifest.json), require a non-empty string `version`, and keep that exact value for the workflow. If the file is missing, invalid JSON, or has no valid `version`, stop before issuing any Alibaba Cloud API call and report the manifest error. Do not guess, hard-code, or fall back to another version.\n- **Session ID**: generate one 32-character lowercase hex session ID once at the start of the workflow (`openssl rand -hex 16`) and reuse that same value for the rest of the session. Keep the generated value and write it out literally in every command that needs it. Do not re-derive it per command, and do not reach for it through a shell variable or a `cat` of a saved file - either one forces an assignment in front of the call and breaks the command shape rule below.\n- **User-Agent**: every `aliyun` CLI cloud API command must carry `--user-agent \"AlibabaCloud-Agent-Skills/alibabacloud-agentloop-management/skill-version/{version}/{session-id}\"`, using the manifest-derived version and the workflow session ID. Bundled wrappers enforce the same manifest gate and format. Local `configure`, `plugin`, and `version` commands are excluded because they are not cloud API calls.\n- **Command shape**: every cloud API call must run as a single-line bare command whose first token is `aliyun`, or `python3` for a bundled wrapper, and whose last token is the final flag of that same call. Nothing may come before it - no `VAR=value` assignment, no `set -o pipefail`, no `source`, no `cd`, no `bash some_script.sh` wrapper - and a newline between an assignment and the call still counts as coming before it. Nothing may come after it either - no `| tee`, no `| head`, no `2>&1`, no `> file` redirect, and no `&&` or `;` chaining onto a second command. Diagnostic probes such as `--help` follow the same rule. When the environment asks for a log of executed actions, run the bare call first and then write the command text and its output into the log as a separate file-write step; a single action log listing each command and its result satisfies that requirement in full, so piping a call into `tee` adds nothing and only corrupts the record of what ran. The command that executes must be the API call itself and nothing else, so that run records, audit trails, and CLI tooling all see it verbatim.\n- **Credential red lines**: never read, echo, or print AK/SK/STS-token values or the APM LicenseKey (`entryPointInfo.authToken`) - in chat answers, summaries, credential tables, generated snippets, or report files. Keep every retrieved credential inside an environment variable, report only whether it was obtained, and reference the variable name instead of the value. Never ask the user to paste literal credentials; never run `aliyun configure set` with literal credential values; use only `aliyun configure list` to check identity status. Onboarding redaction recipe: [references/onboarding.md](references/onboarding.\n\nArchive v0.1.4: 72 files, 258134 bytes\n\nFiles: references/ai.md (14759b), references/apm.md (47049b), references/dataset/data-operations.md (4473b), references/dataset/dataset-management.md (8048b), references/dataset/dataset.md (16559b), references/dataset/query-syntax.md (6376b), references/dataset/ram-policies.md (3619b), references/dataset/related-commands.md (2445b), references/dataset/verification-method.md (4211b), references/evaluation/acceptance-criteria.md (6462b), references/evaluation/api-map.md (8182b), references/evaluation/cli-installation-guide.md (2153b), references/evaluation/evaluation.md (22306b), references/evaluation/examples/batch-dataset-example.json (838b), references/evaluation/examples/batch-trace-example.json (846b), references/evaluation/examples/oneshot-example.json (694b), references/evaluation/ram-policies.md (3775b), references/evaluation/related-commands.md (3320b), references/evaluation/result-analysis.md (3284b), references/evaluation/spec-format.md (9472b), references/evaluation/verification-method.md (2725b), references/onboarding.md (11007b), references/pipeline/nodes-and-expressions.md (6054b), references/pipeline/nodes/_TEMPLATE.md (4409b), references/pipeline/nodes/agentic-call.md (9050b), references/pipeline/nodes/dedup-exact.md (6860b), references/pipeline/nodes/dedup-fuzzy.md (6954b), references/pipeline/nodes/dedup-semantic.md (7916b), references/pipeline/nodes/doc-stats.md (5835b), references/pipeline/nodes/embedding.md (5701b), references/pipeline/nodes/extend.md (5030b), references/pipeline/nodes/limit.md (2315b), references/pipeline/nodes/llm-call.md (9240b), references/pipeline/nodes/make-instance.md (22725b), references/pipeline/nodes/OVERVIEW.md (7994b), references/pipeline/nodes/project.md (5044b), references/pipeline/nodes/sample.md (6021b), references/pipeline/nodes/semantic-cluster.md (6576b), references/pipeline/nodes/where.md (4306b), references/pipeline/operators/_TEMPLATE.md (7040b), references/pipeline/operators/agentic-call.md (14634b), references/pipeline/operators/dedup-exact.md (10561b), references/pipeline/operators/dedup-fuzzy.md (12602b), references/pipeline/operators/dedup-semantic.md (13890b), references/pipeline/operators/dedup.md (26673b), references/pipeline/operators/doc-stats.md (7936b), references/pipeline/operators/embedding.md (7615b), references/pipeline/operators/extend.md (4702b), references/pipeline/operators/limit.md (2632b), references/pipeline/operators/llm-call.md (21165b), references/pipeline/operators/make-instance.md (31234b), references/pipeline/operators/OVERVIEW.md (7946b), references/pipeline/operators/project.md (4429b), references/pipeline/operators/sample.md (10556b), references/pipeline/operators/semantic-cluster.md (9519b), references/pipeline/operators/where.md (3779b), references/pipeline/pipeline-cli-map.md (8628b), references/pipeline/pipeline.md (26228b), references/pipeline/ram-policies.md (6044b), references/pipeline/related-commands.md (6384b), references/pipeline/spec-format.md (8479b), references/pipeline/trace/ot-ai-collection-spec.md (39256b), references/pipeline/trace/ot-ai-trace-recipe.md (7427b), references/pipeline/verification-method.md (8535b), references/ram-policies.md (5747b), scripts/evaluation/agentloop_eval.py (49785b), scripts/evaluation/analyze_evaluation_results.py (18496b), scripts/evaluation/requirements.txt (465b), scripts/pipeline/agentloop_pipeline.py (25381b), skill-card.md (3169b), SKILL.md (8308b), _meta.json (152b)\n\nArchive v0.1.3: 77 files, 272091 bytes\n\nFiles: references/ai.md (14759b), references/apm.md (47049b), references/dataset/data-operations.md (4473b), references/dataset/dataset-management.md (8048b), references/dataset/dataset.md (16559b), references/dataset/query-syntax.md (6376b), references/dataset/ram-policies.md (3619b), references/dataset/related-commands.md (2445b), references/dataset/verification-method.md (4211b), references/evaluation/acceptance-criteria.md (6462b), references/evaluation/api-map.md (8182b), references/evaluation/cli-installation-guide.md (2153b), references/evaluation/evaluation.md (22306b), references/evaluation/examples/batch-dataset-example.json (838b), references/evaluation/examples/batch-trace-example.json (846b), references/evaluation/examples/oneshot-example.json (694b), references/evaluation/ram-policies.md (3775b), references/evaluation/related-commands.md (3320b), references/evaluation/result-analysis.md (3284b), references/evaluation/spec-format.md (9472b), references/evaluation/verification-method.md (2725b), references/experience/context-store-management.md (6732b), references/experience/experience.md (6771b), references/experience/ram-policies.md (1804b), references/experience/search-context-cli.md (4344b), references/onboarding.md (11007b), references/pipeline/nodes-and-expressions.md (6054b), references/pipeline/nodes/_TEMPLATE.md (4409b), references/pipeline/nodes/agentic-call.md (9050b), references/pipeline/nodes/dedup-exact.md (6860b), references/pipeline/nodes/dedup-fuzzy.md (6954b), references/pipeline/nodes/dedup-semantic.md (7916b), references/pipeline/nodes/doc-stats.md (5835b), references/pipeline/nodes/embedding.md (5701b), references/pipeline/nodes/extend.md (5030b), references/pipeline/nodes/limit.md (2315b), references/pipeline/nodes/llm-call.md (9240b), references/pipeline/nodes/make-instance.md (22725b), references/pipeline/nodes/OVERVIEW.md (7994b), references/pipeline/nodes/project.md (5044b), references/pipeline/nodes/sample.md (6021b), references/pipeline/nodes/semantic-cluster.md (6576b), references/pipeline/nodes/where.md (4306b), references/pipeline/operators/_TEMPLATE.md (7040b), references/pipeline/operators/agentic-call.md (14634b), references/pipeline/operators/dedup-exact.md (10561b), references/pipeline/operators/dedup-fuzzy.md (12602b), references/pipeline/operators/dedup-semantic.md (13890b), references/pipeline/operators/dedup.md (26673b), references/pipeline/operators/doc-stats.md (7936b), references/pipeline/operators/embedding.md (7615b), references/pipeline/operators/extend.md (4702b), references/pipeline/operators/limit.md (2632b), references/pipeline/operators/llm-call.md (21165b), references/pipeline/operators/make-instance.md (31234b), references/pipeline/operators/OVERVIEW.md (7946b), references/pipeline/operators/project.md (4429b), references/pipeline/operators/sample.md (10556b), references/pipeline/operators/semantic-cluster.md (9519b), references/pipeline/operators/where.md (3779b), references/pipeline/pipeline-cli-map.md (8628b), references/pipeline/pipeline.md (26245b), references/pipeline/ram-policies.md (6044b), references/pipeline/related-commands.md (6384b), references/pipeline/spec-format.md (8479b), references/pipeline/trace/ot-ai-collection-spec.md (39256b), references/pipeline/trace/ot-ai-trace-recipe.md (7427b), references/pipeline/verification-method.md (8535b), references/ram-policies.md (5947b), scripts/evaluation/agentloop_eval.py (49785b), scripts/evaluation/analyze_evaluation_results.py (18496b), scripts/evaluation/requirements.txt (465b), scripts/experience/search_context.py (17278b), scripts/pipeline/agentl...","readmeExcerpt":"Skill: alibabacloud-agentloop-management Owner: sdk-team Summary: The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTa","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"aliyun sts get-caller-identity --force -o json\n\n# Use user-provided workspace (format: agentloop-{32-char-code})\n# workspace={userProvidedWorkspace}\n\n# Initialize (idempotent)\naliyun cms2 apm configuration create --workspace {workspace} --region {regionId}"},{"language":"bash","snippet":"# LicenseKey goes straight into an env var - never onto a printed line\nexport ARMS_LICENSE_KEY=\"$(aliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json | jq -r '.data.entryPointInfo.authToken')\"\n\n# Non-sensitive fields for the report\naliyun cms2 apm configuration get --workspace {workspace} --region {regionId} -o json \\\n | jq '{status: .data.status,\n licenseKeyObtained: (.data.entryPointInfo.authToken | length > 0),\n publicDomain: .data.entryPointInfo.publicDomain,\n privateDomain: .data.entryPointInfo.privateDomain,\n project: .data.entryPointInfo.project}'"},{"language":"bash","snippet":"aliyun cms2 apm service create --workspace {workspace} --region {regionId} \\\n --body '{\n \"serviceName\": \"{appName}\",\n \"serviceType\": \"{serviceType}\",\n \"attributes\": [\n {\"key\": \"language\", \"value\": \"{language}\"}\n ]\n }'"},{"language":"bash","snippet":"aliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json"},{"language":"bash","snippet":"aliyun cms2 integration addon get --addon-name {addonName} --env-type Client -o json \\\n | jq -r '.data.codeTemplate.codes[] | select(.name==\"{protocol}\") | .codeTemplate'"},{"language":"bash","snippet":"aliyun cms2 apm service list --workspace {workspace} --service-name {appName} --region {regionId} -o json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: alibabacloud-agentloop-management\ndescription: |\n  The skill should be used when the user asks about Alibaba Cloud AgentLoop platform for onboarding applications into observability, high-code instrumentation with loongsuite-genai-utils and OpenTelemetry SDK (高代码埋点、LLM Trace 字段、上下文传递与链路串联), Live-Debug runtime diagnostics, managing Datasets, building pipelines, and evaluating. Live-Debug covers ServiceTask dynamic logging, snapshots, metrics, spans, and JVM inspection.\nlicense: Apache-2.0\nmetadata:\n  domain: aiops\n  owner: agentloop\n  contact: agentloop@alibaba-inc.com\n---\n\n# AgentLoop Skill Router\n\n> **Positioning**: This skill is the single entry point for Alibaba Cloud **AgentLoop** requests. It only classifies the user's intent and dispatches to one of the six domain playbooks below. All executable rules - prerequisites, credentials, RAM policies, parameter confirmation, safety protocols, command usage, and verification - live inside the domain files. Do not run any cloud operation before reading the matched domain file.\n\n**Compatibility**: cloud-operation domains require Aliyun CLI 3.3.15 or later; Pipeline requires `aliyun-cli-agentloop` 0.7.4 or later; bundled evaluation, Pipeline, and public-document retrieval scripts require Python 3.8 or later. Instrumentation guidance and public-document retrieval do not require Aliyun CLI, cloud credentials, or a browser.\n\n## Routing Table\n\n| # | Domain | Intent | Entry file (read first) |\n|---|--------|--------|-------------------------|\n| 1 | Application onboarding (APM & AI observability) | Instrument an application so it reports to AgentLoop: probe or agent install, APM onboarding, `aliyun-bootstrap`, `AliyunJavaAgent`, `instgo`, `cms_node_sdk`, `ack-onepilot`, OpenTelemetry, LicenseKey, K8s/ACK/ECS onboarding, LLM and AI-framework tracing (Dify, LangChain, DashScope) | [references/onboarding.md](references/onboarding.md) - internally routes to [references/apm.md](references/apm.md) / [references/ai.md](references/ai.md) |\n| 2 | Evaluation | Score model, agent, or trace quality: create and update evaluators and evaluator skills, one-shot sample tests, batch trace or Dataset evaluation, trace backfill, poll an evaluation task, analyze results and low-score cases | [references/evaluation/evaluation.md](references/evaluation/evaluation.md) |\n| 3 | Dataset | Store and retrieve structured rows: Dataset lifecycle and schema, append rows with `add-dataset-data`, read-only queries with `execute-query`, SQL or SearchExpr, semantic search, embedding fields | [references/dataset/dataset.md](references/dataset/dataset.md) |\n| 4 | Pipeline | Transform source data into a Dataset once or on a schedule: import Logstore/SLS data into a Dataset, import traces, design specs, preview/create/run, inspect runs, control the lifecycle, configure processing nodes, and map OT AI traces | [references/pipeline/pipeline.md](references/pipeline/pipeline.md) |\n| 5 | Live-Debug runtime diagnostics | Diagnose an already-r"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn74p5w8ywv6prh40g0s82gmqh83nw54\",\n  \"slug\": \"alibabacloud-agentloop-management\",\n  \"version\": \"0.1.5\",\n  \"publishedAt\": 1791528271619\n}"},{"path":"references/ai.md","content":"# AI Observability Module\n\n> Global conventions (credentials, Observability / User-Agent, output format, error codes, command prefix) - see [onboarding.md](onboarding.md).\n> RAM permissions - see [ram-policies.md](ram-policies.md).\n> Run `aliyun cms2 apm <subcommand> --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard AI applications (LLM-based services, AI Agents, custom instrumented apps) into AgentLoop application observability. Uses `aliyun cms2` CLI to initialize APM infrastructure, retrieve access credentials, and generate framework-specific configuration.\n\nFor high-code instrumentation with GenAI Utils / OpenTelemetry SDK, field-format questions, or broken async/cross-process traces, use [instrumentation/instrumentation.md](instrumentation/instrumentation.md) before this cloud workflow. That module dynamically retrieves the language guides, field specification, and all relevant best-practice candidates without requiring a browser or cloud credentials. Return here only when cloud setup is needed.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported AI frameworks.\n\n**Out-of-Scope**: Model fine-tuning or training observability; GPU monitoring (see `cloud-acs-ecs-gpu` addon); general CloudMonitor (CMS) management; `default-cms-*` or other non-`agentloop-*` workspaces; alerts, RUM, Prometheus rules, and other non-onboarding CMS features.\n\n---\n\n## Workspace Mandatory Rules\n\n> **CRITICAL** - AgentLoop AI onboarding requires an explicit AgentLoop workspace from the user.\n\n1. **Always ask user to provide `workspace`**: Never auto-build workspace as `default-cms-{AccountId}-{regionId}`.\n2. **Workspace format is `agentloop-{32-char-code}`**: If missing, run `aliyun cms2 workspace list -o json` and reuse the first `agentloop-[0-9a-f]{32}` match. On quota 403/400, reuse existing `agentloop-*` workspace and continue.\n3. **Do NOT proceed without a valid workspace**: All APM commands require the user-provided or discovered `agentloop-*` workspace.\n\n---\n\n## Execution Safety Protocol\n\nFollow the same Two-Phase Execution Protocol as [apm.md - Execution Safety Protocol](apm.md#execution-safety-protocol).\n\n**Operations that do NOT require confirmation** (execute directly):\n- Read-only commands: `get`, `list`, `--help`\n- AgentLoop platform resource creation: `apm configuration create`, `apm service create`\n- Retrieving credentials: `apm configuration get` (the returned LicenseKey must stay redacted - see [onboarding.md - Credential Output Redaction](onboarding.md#credential-output-redaction))\n- Fetching addon templates: `integration addon get`\n\n**Operations that REQUIRE confirmation** (must use Two-Phase Protocol):\n- Deleting service records: `apm service delete`\n- Modifying user application startup scripts or Dockerfiles\n\n---\n\n## Supported Frameworks\n\n| Framework | Addon Name | Protocols | Underlying Agent |\n|-----------|-----------|-----------|---"},{"path":"references/apm.md","content":"# Application Monitoring (APM) Module\n\n> Global conventions (credentials, Observability / User-Agent, output format, error codes, command prefix) - see [onboarding.md](onboarding.md).\n> RAM permissions - see [ram-policies.md](ram-policies.md).\n> Run `aliyun cms2 apm <subcommand> --help` for full flag lists and examples.\n\n## Scope\n\nGuided workflow to onboard server-side applications into AgentLoop application observability. Uses `aliyun cms2` CLI to initialize APM infrastructure and retrieve access credentials, then generates configuration for the user's specific language and deployment method.\n\n**In-Scope**: Initialize APM infra, retrieve LicenseKey/Endpoint, register app services, generate startup configuration for all supported languages, **auto-modify K8s Deployment YAML** (with user confirmation) via `aliyun cs` + `kubectl`.\n\n**Out-of-Scope (this version)**: Automatic modification of ECS host startup scripts / Dockerfile; agent binary downloads; general CloudMonitor (CMS) management; `default-cms-*` or other non-`agentloop-*` workspaces; alerts, RUM, Prometheus rules, and other non-onboarding CMS features.\n\n---\n\n## Workspace Mandatory Rules\n\n> **CRITICAL** - AgentLoop onboarding requires an explicit AgentLoop workspace from the user. The following rules are **absolute and non-negotiable**.\n\n1. **Always ask user to provide `workspace`**: Never auto-build workspace as `default-cms-{userId}-{regionId}` or any other derived format.\n2. **Workspace format is `agentloop-{32-char-code}`**: Prefix `agentloop-` followed by exactly 32 characters (e.g. `agentloop-2694ecf8****************1f84542d`). If missing or invalid, run `aliyun cms2 workspace list -o json` and reuse the first matching `agentloop-[0-9a-f]{32}` workspace; if none match, stop and prompt: **Please provide a valid AgentLoop workspace in the format `agentloop-{32-char-code}`.**\n3. **Quota fallback**: if workspace creation hits **403/400** quota errors, list existing workspaces, reuse a matching `agentloop-*` workspace, log the reuse reason, and continue - do not abort or fall back to `default-cms-*`.\n4. **Do NOT proceed without a valid workspace**: All `apm configuration` / `apm service` commands require `--workspace`; do not guess or fabricate a value.\n5. **Region must be obtained separately**: `regionId` is NOT encoded in the workspace name. Derive it from cluster metadata or kubeconfig context in container flows; ask the user in non-container flows.\n\n---\n\n## Container Onboarding Mandatory Rules\n\n> **CRITICAL** - When the user selects container (ACK/ACS/K8s) onboarding, the following rules are **absolute and non-negotiable**. Violating any of them is a workflow error.\n\n1. **Do NOT ask user for `regionId`**: In container onboarding, `regionId` must be derived automatically from cluster metadata or kubeconfig context. Never prompt the user for region. If derivation fails, use `aliyun cs describe-clusters` output to extract `region_id` from cluster info.\n2. **Do NOT run any `integration ad"},{"path":"references/dataset/data-operations.md","content":"# Dataset Data Operations\n\n## Append Structured Rows\n\nPrefer `add-dataset-data` for normal inserts. It accepts typed JSON and avoids SQL escaping mistakes.\n\n```bash\naliyun agentloop add-dataset-data \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --data-array '[\n    {\n      \"question\":\"How do I inspect an error?\",\n      \"answer\":\"Start with the request ID.\",\n      \"score\":0.95,\n      \"metadata\":{\"source\":\"manual\",\"latency_ms\":120}\n    },\n    {\n      \"question\":\"How do I retry safely?\",\n      \"answer\":\"Reuse the same idempotency token.\",\n      \"score\":0.91,\n      \"metadata\":{\"source\":\"reviewed\",\"latency_ms\":85}\n    }\n  ]' \\\n  --client-token <client_token>\n```\n\nRules:\n\n- `dataArray` cannot be empty and every item must be a JSON object.\n- All rows in one request are committed atomically.\n- The maximum request body is 100 MiB (`100 * 1024 * 1024` bytes). There is no separate fixed API row-count limit; the server streams rows and keeps the request atomic.\n- Unknown fields fail the whole request.\n- Missing schema fields are stored as `null`.\n- Field names are matched case-insensitively; duplicate case variants are rejected.\n- `text` accepts strings, `long` accepts integers, `double` accepts finite numbers, and `json` accepts any valid JSON value.\n- Omit `id` to auto-generate it. A supplied `id` must be a UUID.\n- Omit `__time__` to use the current Unix time. A supplied value must be non-null and a non-negative integer in seconds.\n- Never supply `__dataset_seq`.\n\nBefore dry-run, compare every row's keys and nested values with the user's requested data, separately from schema validation. The payload may contain only user-authorized fields supported by the schema, plus system fields the user explicitly supplied. Existing optional schema fields may remain omitted; their presence is not permission to populate them. If the user requests a marker in `agentloop_annotations`, keep it inside that object, even if the schema also has a top-level `marker_id`. Do not add or duplicate a field to make verification easier.\n\nDry-run complex row-array structure and inspect that booleans, numbers, objects, arrays, and null values retain their JSON types. If rows contain real prompts, outputs, tokens, PII, or other sensitive content, use a shape-equivalent synthetic array for dry-run; do not print the real request body into terminal history or conversation output:\n\n```bash\naliyun agentloop add-dataset-data \\\n  --region <region_id> \\\n  --agent-space <agent_space_name> \\\n  --dataset-name <dataset_name> \\\n  --data-array '<json_array>' \\\n  --client-token <client_token> \\\n  --cli-dry-run\n```\n\nSuccess returns `requestId` and `affectedRows`. Verify `affectedRows` equals the submitted row count, then query a narrow sample.\n\nUse the same authorized field structure for the serialized dry-run body and the real write. Successful serialization or API acceptance does not prove that extra fields were requested. When the requested readbac"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2341,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T14:51:50.806Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T17:42:29.549Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}