Query Netdata Agents

Safe Execution

Use agents_query_cloud, agents_query_agent or agents_call_function for credential-bearing requests. Do not write raw curl commands containing live auth headers or invoke internal mint helpers directly. Header notation in the auth reference describes the protocol, not a request to expose credentials. Unauthenticated probes and local processing MAY use ordinary commands when they capture or suppress sensitive response fields.

The wrappers mask request-auth values in their command log and keep internal mint/claim discovery private. They forward endpoint responses unchanged: logs, config and identity responses can contain secrets or identifiers. Cloud tokens, Agent bearers and claim IDs MUST NOT reach assistant-visible output. Capture sensitive responses in a shell variable or private local artifact, or pipe directly to an appropriate field projection before display. Do not use a general query wrapper to display a credential-issuing endpoint's response. Masked request logging is not response sanitization; do not enable shell tracing around credentials.

For example, after choosing the requested target locally:

source "$(git rev-parse --show-toplevel)/docs/netdata-ai/skills/query-netdata-agents/scripts/_lib.sh"
agents_load_env
agents_query_agent \
  --node "${NODE_UUID:?set the node UUID}" --host "${AGENT_HOST:?set the Agent host:port}" \
  --machine-guid "${AGENT_MG:?set the machine GUID}" \
  POST '/api/v3/function?function=systemd-journal' '{"info":true}' \
  | jq '{status, type}'

For an execution recipe, provide a complete runnable invocation and the response fields needed for the question. Explanations and reviews do not need an unrelated live command appended. Function-specific parameters and output projections belong in the domain guide. Helper Interfaces records all public interfaces, credential/cache handling and safe test commands.

Bearers stay in local configuration/cache or private in-memory variables. Never commit credential values, claim IDs, node UUIDs or machine GUIDs. Repository users follow .agents/sensitive-data-discipline.md; outside a checkout, apply the same redaction to shared artifacts. A private cache is not an artifact to display or publish.

Knowledge Capture

• For answer-only questions, deliver the requested answer. If the work reveals a reusable, evidence-backed recipe not already documented, you MUST preserve a sanitized note with the finding, supporting evidence, and proposed owning guide. In a repository checkout, use <repo-root>/.local/audits/<subject>/followups.md, reusing this skill's audit directory when available. Outside a checkout, use an appropriate local workspace. If no writable workspace is available, include the sanitized follow-up in the response instead.
• Briefly report reusable documentation discoveries and proposed updates in the answer-only final response, even when recorded locally. Obtain authorization before those guide edits; do not delay the answer while awaiting it.
• During authorized implementation, you MUST update this skill or its guides for reusable, evidence-backed discoveries made while doing the work, even when the documentation is not required for the code change. This needs no separate authorization. Keep how-tos/INDEX.md consistent and report the updates.
• Guide edits arising from answer-only questions require separate authorization. Documentation capture records observed behavior; it does not authorize additional implementation or new product contracts. Commit and publication require authorization too.
• Prefer updating an existing guide over duplicating it. Keep recipes operator-facing: fetching or using Agent data. Developer contract validation for topology producers, schemas, fixtures, UI adapters, or aggregator handoffs belongs in the relevant project developer skill, not in this public skill.