aiq-configure-workflow

# Configure AI-Q Workflows Use this skill when a developer or operator needs a **new `configs/config_*.yml`** file. ## Start Here - Confirm this is **config composition** — not deploy (`aiq-deploy`), live research (`aiq-research`), prompt edits (`aiq-customize-prompts-models`), or new NAT packages (`aiq-add-tool` / `aiq-add-data-source`). - Copy the closest shipped `configs/*.yml` profile; merge feature blocks from others. - **Every produced config must pass `validate_config.py` before hand-off.** ## Authoritative References - `docs/source/customization/configuration-reference.md` — all fields and defaults - `docs/source/customization/tools-and-sources.md` - `docs/source/deployment/observability.md` — tracing setup detail - `frontends/aiq_api/README.md` - `configs/config_web_default_llamaindex.yml` / `configs/config_cli_default.yml` Bundle: - [references/config-profiles.md](references/config-profiles.md) — pick a starting profile. - [references/composing-config.md](references/composing-config.md) — holistic config map (`general`, `llms`, `functions`, `workflow`, telemetry, `aiq_api`) and how to tune them. - [references/env-vars.md](references/env-vars.md) — environment variables by config feature. - [references/config-schema.md](references/config-schema.md) — validator checks only. - [assets/config-scaffold.yml](assets/config-scaffold.yml) — fallback scaffold. ## Workflow 1. **Scaffold** — `cp configs/<profile>.yml configs/config_<name>.yml` (or [assets/config-scaffold.yml](assets/config-scaffold.yml) + merge blocks). 2. **Compose** — [references/composing-config.md](references/composing-config.md): adjust registry, tools, agents, LLMs, telemetry, `aiq_api`, workflow flags. Use `config_web_default_llamaindex.yml` as the live default for web `general:` blocks; `configuration-reference.md` for every option. Use [references/env-vars.md](references/env-vars.md) for feature-specific env vars. 3. **Validate (required)** — ```bash uv run python .agents/skills/aiq-configure-workflow/scripts/validate_config.py configs/config_<name>.yml ``` Fix every `ERROR:`; re-run until exit code 0. Then hand off to `aiq-deploy` or: ```bash dotenv -f deploy/.env run nat serve --config_file configs/config_<name>.yml --port 8000 ``` ## Validation ```bash uv run python .agents/skills/aiq-configure-workflow/scripts/validate_config.py <config.yml> ``` See [references/config-schema.md](references/config-schema.md). Expected: exit 0. ## Common Mistakes - Skipping `validate_config.py` on a new config. - Undefined `llms:` alias or registry tool not declared under `functions:`. - Missing functions required by the selected workflow: the chat workflow needs `intent_classifier`, `shallow_research_agent`, and `deep_research_agent`; the direct DS workflow needs `data_science_agent`. - `use_async_deep_research: true` without `general.front_end` (`aiq_api`). - Inventing feature YAML — copy from a shipped profile. ## Related Skills - `aiq-deploy` - `aiq-research` - `aiq-customize-prompts-models` - `aiq-add-tool` - `aiq-add-data-source` - `aiq-release-qa` - `aiq-prepare-pr`