ID References

Directives deprecated

$ref, $use, resource::, local::, global::, and selector expressions like #(...) were removed. Configs with $-prefixed directives fail validation. Use the ID-based patterns below.

Overview

Compozy now resolves resources by stable IDs through a Resource Store. You reference components directly by ID, and the engine links them at compile time.

Agents: agent: writer or agent: { id: writer }
Tools: tool: http_client or tools: [http_client, file_reader]
MCP servers: mcp: github or in agents mcps: [github, filesystem]
Schemas: set fields to the schema ID, e.g. config: { input: user_input }
Models: model: openai:gpt-4o-mini

Workflow References

workflow.yaml

id: example

schemas:
  - id: user_input
    type: object
    properties:
      name: { type: string }
    required: [name]

config:
  input: user_input  # reference by ID (no $ref)

agents:
  - id: greeter
    model: openai:gpt-4o-mini
    instructions: |
      Write a friendly greeting.
    tools: [greeting_tool]   # reference tool IDs

tools:
  - id: greeting_tool
    input: user_input        # schema by ID

tasks:
  - id: greet
    type: basic
    agent: greeter           # agent by ID
    action: create_greeting
    with:
      name: "{{ .workflow.input.name }}"
    final: true

Agent, Tool, MCP in Tasks

Use exactly one of agent, tool, or mcp in a basic task.

- id: run_with_agent
  type: basic
  agent: writer
  action: draft

- id: run_with_tool
  type: basic
  tool: http_client
  with:
    url: https://api.example.com

- id: run_with_mcp
  type: basic
  mcp: github
  with:
    op: list_issues

Schema References

Provide schema IDs at any input/output schema field:

config:
  input: order_input

agents:
  - id: order_agent
    actions:
      - id: analyze
        output: analysis_result

tools:
  - id: validator
    input: order_input
    output: validation_result

Models as Resources

Agents can select a model by ID:

agents:
  - id: analyst
    model: openai:gpt-4o-mini

During compile, the model config is resolved and merged according to project precedence.

When AutoLoad is enabled, discovered resources are registered in an in-memory registry and can be published to the Resource Store. ID-based linking then resolves all references during workflow compile. See AutoLoad.