# How to Manage Agent Dependencies Specified in YAML Headers in aios-core

> Learn to manage AIOS agent dependencies defined in YAML headers. Discover how the aios-core framework uses DAGs to validate and resolve dependencies at runtime for efficient agent operation.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-19

---

**AIOS agents declare required artefacts in a `dependencies` section within the YAML header, which the framework validates through a wizard and resolves at runtime via a directed-acyclic graph built by the registry loader.**

Managing agent dependencies specified in YAML headers in aios-core ensures that workflows, tasks, templates, and scripts are available before an agent activates. The framework validates these declarations during development through the wizard and orchestrates their loading at runtime through the core registry system in [`.aios-core/core/registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/core/registry-loader.js).

## Structure of the Dependencies Header

The `dependencies` section in an agent YAML file supports six optional categories. Each category lists artefacts required by the agent:

```yaml
dependencies:
  workflows:
    - myagent-build-ui.yaml
    - myagent-deploy.yaml
  tasks:
    - myagent-generate-docs.md
    - myagent-run-tests.md
  templates:
    - myagent-report-tmpl.yaml
  checklists:
    - myagent-release-checklist.md
  data:
    - myagent-data.json
  scripts:
    - myagent-setup.js
  tools:
    - myagent-cli-tool.yaml

```

### Naming Conventions

AIOS enforces strict naming rules to distinguish between agent-specific and shared artefacts.

**Agent-specific artefacts** must prefix with the agent's `id` as defined in the YAML header. According to [`.aios-core/product/templates/agent-template.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/product/templates/agent-template.yaml) lines 9-15, all dependencies specific to an agent must follow this naming convention.

**Shared artefacts** live in the global namespace and must not use the agent prefix. These are stored in shared folders such as `tasks/` or `scripts/`. See [`.aios-core/product/templates/agent-template.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/product/templates/agent-template.yaml) lines 24-27 for the distinction between local and shared namespaces.

## Declaring Dependencies in Agent YAML Files

A complete agent definition combines the header with persona and command definitions. Below is a real-world example from [`docs/guides/squad-examples/simple-agent.yaml`](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/squad-examples/simple-agent.yaml):

```yaml

# myagent.yaml – Documentation Assistant

agent:
  name: "Docs-Helper"
  id:   "myagent"
  title: "Documentation Assistant"
  icon: "📚"

persona:
  role:   "Technical Writer"
  style:  "concise"
  focus:  "API docs, READMEs"

commands:
  - help: "Show available commands"
  - generate-readme: "Create a README from source"
  - document-api:   "Generate API reference"

dependencies:
  workflows:
    - myagent-readme-generator.yaml
    - myagent-api-documenter.yaml
  tasks:
    - myagent-validate-docs.md
  scripts:
    - myagent-cleanup.js

```

Notice that all local artefacts use the `myagent-` prefix, adhering to the naming convention enforced by the validation layer in [`tests/unit/wizard/validation/dependency-validator.test.js`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/wizard/validation/dependency-validator.test.js).

## Validating and Updating Dependencies with the Wizard

The AIOS wizard validates dependency declarations before runtime. Follow this workflow when adding or updating dependencies:

1. **Create the artefact** using the appropriate naming convention (prefixed for local, unprefixed for shared).

2. **Open the agent YAML** and add the reference under the correct sub-key (`workflows`, `tasks`, `scripts`, etc.).

3. **Run the wizard** using `npm run sync:ide` or `aios wizard`. The wizard performs three critical checks:
   - Verifies the file exists on disk.
   - Confirms the path resides inside permitted folders (`.aios-core/development/...`).
   - Updates the **entity-registry** ([`.aios-core/data/entity-registry.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/data/entity-registry.yaml)) so the orchestrator recognizes the new relationship.

4. **Commit** the new files and the updated agent YAML to version control.

The validation logic that enforces these rules is implemented in [`tests/unit/wizard/validation/dependency-validator.test.js`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/wizard/validation/dependency-validator.test.js), which guards against missing files, naming violations, and incorrect categorization.

## Runtime Resolution and Execution

When an agent activates, the core orchestration layer resolves dependencies through a directed-acyclic graph (DAG). The process operates in four stages:

**Parse YAML** – The [`agent-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/agent-loader.js) reads the header and extracts the `dependencies` object:

```javascript
// core/orchestration/agent-loader.js (excerpt)
const { dependencies } = yaml.load(agentYaml);
if (dependencies?.workflows) {
  dependencies.workflows.forEach(wf => loadWorkflow(wf));
}

```

**Build Graph** – The [`registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/registry-loader.js) constructs a DAG to ensure artefacts load in the correct order, resolving "used-by" links and lazy-loading shared resources as defined in [`agent-config-requirements.yaml`](https://github.com/SynkraAI/aios-core/blob/main/agent-config-requirements.yaml).

**Lazy-Load Resources** – Shared sections are loaded on-demand according to the global lazy-loading strategy specified in [`.aios-core/data/agent-config-requirements.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/data/agent-config-requirements.yaml).

**Execute** – The [`workflow-executor.js`](https://github.com/SynkraAI/aios-core/blob/main/workflow-executor.js) runs the required workflows and tasks in dependency order.

If resolution fails due to a missing file or circular reference, the orchestrator aborts and emits a clear error identifying the offending artefact.

## Common Pitfalls and Solutions

| Issue | Symptom | Solution |
|-------|---------|----------|
| **Wrong prefix** | Validation error: "Dependency not found in shared namespace" | Remove the agent prefix and place the file under `tasks/` or other shared folders. |
| **Circular dependency** | Orchestrator throws "Dependency cycle detected" | Collapse the cycle by moving common steps to a shared script or checklist. |
| **Missing file** | Wizard prints "Missing …" | Add the file to the repository or remove the entry from the agent YAML. |
| **Incorrect category** | Runtime loads the artefact as the wrong type and fails to parse | Move the entry to the correct sub-key (e.g., `workflows` instead of `tasks`). |

The wizard's unit tests in [`tests/unit/wizard/validation/dependency-validator.test.js`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/wizard/validation/dependency-validator.test.js) protect against all of these scenarios during the development phase.

## Quick Reference Code Snippets

**Minimal dependency block (single workflow):**

```yaml
dependencies:
  workflows:
    - myagent-main.yaml

```

**Adding a shared script:**

```yaml
dependencies:
  scripts:
    - cleanup-temp-files.js   # shared – no myagent- prefix

```

**Programmatic lookup (core implementation):**

```javascript
// core/orchestration/agent-loader.js (excerpt)
const { dependencies } = yaml.load(agentYaml);
if (dependencies?.workflows) {
  dependencies.workflows.forEach(wf => loadWorkflow(wf));
}

```

## Summary

- **Declare dependencies** in the YAML header under the `dependencies` key, using sub-keys for `workflows`, `tasks`, `templates`, `checklists`, `data`, `scripts`, and `tools`.
- **Follow naming conventions** – prefix agent-specific artefacts with the agent `id`; leave shared artefacts unprefixed.
- **Validate changes** by running the wizard (`npm run sync:ide` or `aios wizard`), which checks file existence, paths, and updates [`.aios-core/data/entity-registry.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/data/entity-registry.yaml).
- **Runtime resolution** occurs through [`registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/registry-loader.js), which builds a DAG to load artefacts in the correct order, with lazy-loading governed by [`agent-config-requirements.yaml`](https://github.com/SynkraAI/aios-core/blob/main/agent-config-requirements.yaml).

## Frequently Asked Questions

### What happens if I forget to prefix an agent-specific dependency?

The wizard validation will fail with an error indicating the dependency was not found in the shared namespace. According to [`tests/unit/wizard/validation/dependency-validator.test.js`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/wizard/validation/dependency-validator.test.js), the system checks that agent-specific artefacts use the correct `id` prefix. To fix this, either add the agent prefix to the filename or move the file to a shared folder and remove the prefix from the reference.

### Can an agent depend on artefacts from another agent?

Yes, but only on shared artefacts that reside in the global namespace. As defined in [`.aios-core/product/templates/agent-template.yaml`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/product/templates/agent-template.yaml) lines 24-27, shared artefacts do not use an agent prefix and can be referenced by any agent. Agent-specific artefacts (with prefixes) are private to that agent and cannot be referenced by others to maintain encapsulation.

### How does the runtime handle circular dependencies between workflows?

The orchestrator detects cycles during the graph construction phase in [`registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/registry-loader.js). If workflow A depends on task B, which in turn references workflow A, the system throws a "Dependency cycle detected" error and aborts activation. To resolve this, refactor common steps into a shared script or checklist that both workflows can reference without creating a circular reference.

### What is the difference between the validation stage and runtime resolution?

Validation occurs during development when you run the wizard (`npm run sync:ide`), which executes the checks in [`tests/unit/wizard/validation/dependency-validator.test.js`](https://github.com/SynkraAI/aios-core/blob/main/tests/unit/wizard/validation/dependency-validator.test.js) to verify file existence, naming conventions, and path permissions. Runtime resolution happens when the agent activates, where [`core/orchestration/agent-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/core/orchestration/agent-loader.js) parses the YAML and [`registry-loader.js`](https://github.com/SynkraAI/aios-core/blob/main/registry-loader.js) builds the dependency graph to load artefacts in the correct order.