The reference graph
How objects in a Package refer to each other, and the order they're installed in.
Objects in a Package refer to each other by manifest-local name, written <collection>.<name>:
| Collection | Example reference |
|---|---|
agents | agents.intake |
teams | teams.after-hours-desk |
workflows | workflows.triage-flow |
tools | tools.calendar |
skills | skills.urgency-classification |
knowledgeBases | knowledgeBases.escalation-policy |
Where they appear: a Team's members[].agent, a Workflow node's agent or team, an Agent's
tools and knowledge.knowledge_bases, a voice configuration's agent, the manifest's
entryPoint and each Slot's boundTo.
What validate checks
| Check | Error code |
|---|---|
| Every reference names an object the manifest declares | UNRESOLVED_LOCAL_REFERENCE |
| The entry point names a declared object | ENTRY_POINT_NOT_FOUND |
| No loop, e.g. a Workflow that calls a Team whose Agent calls the same Workflow | CYCLE_DETECTED (the error lists the whole loop) |
| Names are unique within their collection | MANIFEST_DUPLICATE_NAME |
validate reads the definition files to find these references, which is why every ref must point
at a real file. An unresolved reference's hint names the declared objects you might have meant.
Install order
The graph gives a dependency order, and every install follows it:
- Capabilities first: Tools, Skills and Knowledge Bases.
- Agents, which can now be wired to their Tools and Knowledge Bases.
- Teams, once every member Agent exists.
- Workflows, once every Agent and Team they call exists.
- Voice and SIP, then the entry point is wired to its triggers.
The order comes from the references, not from the order you list objects in the manifest.
References outside the Package
After installation, the objects are ordinary resources and operators can connect them to anything else. When a Package is uninstalled or updated, the same graph (plus anything outside the Package now referencing its objects) decides what can safely be removed. See Update and uninstall.