Add an AI-Q Tool
Use this skill when a developer wants to add a general-purpose tool to AI-Q — a
NeMo Agent Toolkit (NAT) function such as a web search, calculator, or code
helper. The tool is a package under sources/, registered with
@register_function and referenced directly in an agent's tools list.
Start Here
- Confirm this is a general utility tool. If it is domain-specific retrieval
that should appear as a toggleable source in the UI, use
aiq-add-data-source
instead — a data source is the same NAT function plus a data_source_registry
entry. This skill stops at wiring the tool into an agent.
- Read the authoritative files below before editing.
- Copy the closest existing tool package rather than inventing a new shape.
- Never print or commit API keys; resolve secrets at runtime via
SecretStr.
Authoritative References
docs/source/extending/adding-a-tool.md: canonical 8-step walkthrough; the
workflow below mirrors it.
sources/tavily_web_search/: minimal tool package.
sources/google_scholar_paper_search/: tool package with a separate client,
a graceful missing-secret stub, and tests.
docs/source/extending/adding-a-data-source.md: "Data Source vs. Tool" — a
data source is architecturally identical to a tool; only the registry wiring
differs.
Existing tools to model on: tavily_web_search, exa_web_search,
paper_search (Google Scholar), knowledge_retrieval.
Longer procedures live in this bundle:
- references/nat-function-pattern.md:
package layout, config class, registration, the missing-secret stub, the
pyproject.toml entry point, and wiring the tool into an agent in YAML.
- references/testing.md: unit-test pattern and the
install/test/lint validation commands.
Workflow
- Pick the closest existing package under
sources/ and inspect its layout.
- Create
sources/<my_tool>/ with src/register.py, a client module,
pyproject.toml, and tests/.
- Define a
FunctionBaseConfig subclass with a stable name= (this becomes the
YAML _type); resolve any API key via SecretStr.
- Register an async
@register_function that yields a FunctionInfo; yield a
graceful stub when a required secret is missing.
- Add the
[project.entry-points."nat.plugins"] entry and install the package
editable.
- Reference the tool in a config under
configs/ (under functions:, then in
an agent's tools: list).
- Add focused tests; run the validation commands below.
- Summarize changed files and paste the test/lint evidence.
Validation
Run the narrowest commands first; broaden only if the change touches shared code.
uv pip install -e ./sources/my_tool
uv run pytest sources/my_tool/tests
uv run ruff check sources/my_tool
uv run ruff format --check sources/my_tool
Expected: the package installs, its tests pass, and Ruff reports no lint or
format failures for the new tool package.
Common Mistakes
- Omitting the
[project.entry-points."nat.plugins"] entry in pyproject.toml,
so NAT never discovers the registration at import time.
- Crashing on a missing API key instead of yielding a stub that returns a clear
error string.
- Raising exceptions from the tool function; tools must return error messages as
strings so they never crash the agent.
- Weak docstrings: the LLM uses the function docstring as the tool description to
decide when to call it — state what it does, when to use it, and what it returns.
- Printing API keys or embedding secrets in YAML instead of using environment
variables or
SecretStr.
Related Skills
aiq-configure-workflow
aiq-add-data-source
aiq-release-qa
aiq-prepare-pr
1---2name: aiq-add-tool3description: Use when adding or changing a general-purpose AI-Q tool (a NeMo Agent Toolkit function) under sources/, defining its FunctionBaseConfig schema, registering it with @register_function, wiring it into an agent's tools list, or testing it.4license: Apache-2.05compatibility: Claude Code, Codex, Cursor, OpenCode, and Agent Skills-compatible tools.6metadata:7 source: https://skillmd.com/skills/nvidia-ai-blueprints-aiq/aiq-add-tool8 version: "0.1.0"9 source-repo: "NVIDIA-AI-Blueprints/aiq"10 tags: "aiq nemo-agent-toolkit tool function sources"11allowed-tools: Read Bash Edit12---1314# Add an AI-Q Tool1516Use this skill when a developer wants to add a general-purpose tool to AI-Q — a17NeMo Agent Toolkit (NAT) function such as a web search, calculator, or code18helper. The tool is a package under `sources/`, registered with19`@register_function` and referenced directly in an agent's `tools` list.2021## Start Here2223- Confirm this is a **general utility tool**. If it is domain-specific retrieval24 that should appear as a toggleable source in the UI, use `aiq-add-data-source`25 instead — a data source is the same NAT function plus a `data_source_registry`26 entry. This skill stops at wiring the tool into an agent.27- Read the authoritative files below before editing.28- Copy the closest existing tool package rather than inventing a new shape.29- Never print or commit API keys; resolve secrets at runtime via `SecretStr`.3031## Authoritative References3233- `docs/source/extending/adding-a-tool.md`: canonical 8-step walkthrough; the34 workflow below mirrors it.35- `sources/tavily_web_search/`: minimal tool package.36- `sources/google_scholar_paper_search/`: tool package with a separate client,37 a graceful missing-secret stub, and tests.38- `docs/source/extending/adding-a-data-source.md`: "Data Source vs. Tool" — a39 data source is architecturally identical to a tool; only the registry wiring40 differs.4142Existing tools to model on: `tavily_web_search`, `exa_web_search`,43`paper_search` (Google Scholar), `knowledge_retrieval`.4445Longer procedures live in this bundle:4647- [references/nat-function-pattern.md](references/nat-function-pattern.md):48 package layout, config class, registration, the missing-secret stub, the49 `pyproject.toml` entry point, and wiring the tool into an agent in YAML.50- [references/testing.md](references/testing.md): unit-test pattern and the51 install/test/lint validation commands.5253## Workflow54551. Pick the closest existing package under `sources/` and inspect its layout.562. Create `sources/<my_tool>/` with `src/register.py`, a client module,57 `pyproject.toml`, and `tests/`.583. Define a `FunctionBaseConfig` subclass with a stable `name=` (this becomes the59 YAML `_type`); resolve any API key via `SecretStr`.604. Register an async `@register_function` that yields a `FunctionInfo`; yield a61 graceful stub when a required secret is missing.625. Add the `[project.entry-points."nat.plugins"]` entry and install the package63 editable.646. Reference the tool in a config under `configs/` (under `functions:`, then in65 an agent's `tools:` list).667. Add focused tests; run the validation commands below.678. Summarize changed files and paste the test/lint evidence.6869## Validation7071Run the narrowest commands first; broaden only if the change touches shared code.7273```bash74uv pip install -e ./sources/my_tool75uv run pytest sources/my_tool/tests76uv run ruff check sources/my_tool77uv run ruff format --check sources/my_tool78```7980Expected: the package installs, its tests pass, and Ruff reports no lint or81format failures for the new tool package.8283## Common Mistakes8485- Omitting the `[project.entry-points."nat.plugins"]` entry in `pyproject.toml`,86 so NAT never discovers the registration at import time.87- Crashing on a missing API key instead of yielding a stub that returns a clear88 error string.89- Raising exceptions from the tool function; tools must return error messages as90 strings so they never crash the agent.91- Weak docstrings: the LLM uses the function docstring as the tool description to92 decide when to call it — state what it does, when to use it, and what it returns.93- Printing API keys or embedding secrets in YAML instead of using environment94 variables or `SecretStr`.9596## Related Skills9798- `aiq-configure-workflow`99- `aiq-add-data-source`100- `aiq-release-qa`101- `aiq-prepare-pr`