Yaml Files

Compose Agents & Orchestrators from YAML

compose_from_yaml lets you materialize agents and orchestration topologies directly from YAML. It targets enterprise scenarios where repeatability, auditability, and scale matter: define once, deploy anywhere.

What it does

  • Batch Agent Provisioning — Instantiate many agents from a single YAML spec.

  • Orchestrator Topologies — Build Crowe “collectives” (majority vote, hierarchical, graph, etc.) when defined in YAML.

  • Structured Observability — First-class logging (e.g., Loguru-compatible hooks) for run traces and diagnostics.

  • Flexible Return Contracts — Return an orchestrator, agent set, both, or task outcomes depending on your needs.

  • Deep Customization — Pass extra *args/**kwargs to override YAML at runtime (per-env tweaks, flags, guards).

  • Resilient Error Handling — Clear messages for missing keys, invalid shapes, or incompatible wiring.

Signature

compose_from_yaml(
    model_provider: callable | None = None,
    config_path: str = "agents.yaml",
    return_mode: str = "auto",          # "auto" | "orchestrator" | "agents" | "both" | "tasks" | "run"
    *args,
    **kwargs
) -> Any

Parameters

  • model_provider A callable that returns the model backend an agent will use (LLM or otherwise). Example: OpenAIChat(model_name="gpt-5"), vLLM(endpoint=...), or your in-house inference client.

  • config_path Path to the YAML file describing agents, tools, memory, and an optional orchestration graph. Example: "configs/prod/agents.yaml"

  • return_mode Controls what you get back:

    • "auto" — Choose the most meaningful artifact from the YAML (orchestrator if present; otherwise agents).

    • "orchestrator" — Return the Crowe orchestrator (router/graph/collective) if defined; fall back to agents if not.

    • "agents" — Return a single Agent or a List[Agent].

    • "both" — Return (orchestrator, [agents...]).

    • "tasks" — Execute configured tasks and return their results.

    • "run" — Execute the orchestrator end-to-end and return the final output.

  • args / kwargs Runtime overrides (e.g., temperature=0.2, verbose=True, workspace="/mnt/...") to augment or replace YAML fields.

Return Shapes

Mode
Returns
When it Applies

auto

Orchestrator or Agent(s)

Prefers orchestrator if YAML declares one

orchestrator

CroweRouter / CroweGraph / Collective

YAML defines an orchestration structure

agents

Agent or List[Agent]

YAML only defines agents

both

(orchestrator, List[Agent])

YAML defines both orchestration and agents

tasks

List[Dict]

YAML includes tasks: to run at load time

run

Any (final run output)

You want compose+execute in a single call

invalid

None

Invalid mode or structural error

Operational Notes

  • Logging — Crowe integrates cleanly with Loguru/structlog; enable JSON logs for SIEM pipelines.

  • Overrides — Any kwargs passed to compose_from_yaml take precedence over YAML (per-env tuning without forking configs).

  • Schema Safety — YAML is validated before materialization; errors point to exact paths for quick fixes.

  • Local Models — Prefer not to use hosted APIs? Provide a model_provider backed by vLLM (or other self-hosted inference) to keep data in your perimeter.

  • Idempotency — Repeated compositions from the same YAML yield identical topologies unless overrides differ.

YAML Schema Overview

This section outlines the Crowe YAML configuration schema — the blueprint that defines how agents and orchestrators are instantiated and connected. Every attribute listed here directly impacts runtime behavior, scalability, and the nature of collaboration between agents.

Agent Definitions (agents)

Each entry under agents describes a single operational unit in your Crowe system.

Attribute
Description
Type
Required
Default / Example

agent_name

Unique identifier for the agent. Used for routing, logging, and debugging.

string

✅ Yes

"Market-Intel-Agent"

system_prompt

The instruction set or role definition for the agent.

string

✅ Yes

"You specialize in synthesizing real-time market intelligence."

max_loops

Maximum number of iterative reasoning cycles.

int

❌ No

1

autosave

Persist agent state to disk after each run.

bool

❌ No

true

dashboard

Enable a live dashboard view for this agent.

bool

❌ No

false

verbose

Enable verbose logging for step-by-step debugging.

bool

❌ No

false

dynamic_temperature_enabled

Allow runtime adjustment of model temperature based on context.

bool

❌ No

false

saved_state_path

Path to serialized agent state for warm starts.

string

❌ No

"checkpoints/agent_state.json"

user_name

Label for the human or system interacting with the agent.

string

❌ No

"default_user"

retry_attempts

Number of retry cycles on recoverable errors.

int

❌ No

1

context_length

Maximum token length the agent can handle in memory.

int

❌ No

100000

return_step_meta

Return per-step metadata in responses.

bool

❌ No

false

output_type

Desired output format ("str", "json", "dict", etc.).

string

❌ No

"str"

task

(Optional) A pre-assigned task for immediate execution.

string

❌ No

"Evaluate renewable energy sector trends."

Orchestrator Definition (orchestrator) — Optional

When defined, the orchestrator coordinates multiple agents according to a chosen workflow strategy.

Attribute
Description
Type
Required
Default / Example

name

Human-readable identifier for the orchestrator.

string

✅ Yes

"Global-Research-Orchestrator"

description

Purpose and scope of the orchestrator.

string

❌ No

"Coordinates multi-agent research and synthesis workflows."

max_loops

Max iteration cycles for orchestrator-level reasoning.

int

❌ No

5

orchestrator_type

Execution strategy ("ConcurrentWorkflow", "SequentialWorkflow", "VotingWorkflow", etc.).

string

✅ Yes

"ConcurrentWorkflow"

task

The main orchestration-level task.

string

❌ No

"Assess Q4 market risks across all tracked sectors."

Example YAML

agents:
  - agent_name: "Market-Data-Collector"
    system_prompt: "Gather and structure sector-specific market data."
    max_loops: 1
    autosave: true
    verbose: false
    retry_attempts: 2
    output_type: "json"

  - agent_name: "Risk-Analyst"
    system_prompt: "Identify and quantify potential investment risks."
    max_loops: 1
    dashboard: true

orchestrator:
  name: "Investment-Strategy-Orchestrator"
  description: "Combines market data and risk analysis to form investment strategies."
  orchestrator_type: "SequentialWorkflow"
  max_loops: 3
  task: "Produce a quarterly investment strategy report."

Design Notes

  • Minimal vs. Full Configs — Start with agent_name + system_prompt for prototypes; layer on orchestration as needs grow.

  • Runtime Overrides — CLI flags or Python kwargs to compose_from_yaml will override YAML values without editing the file.

  • Schema Validation — Crowe enforces schema compliance before execution, failing fast on invalid configurations.

  • Extensibility — The schema supports custom keys if your loaders know how to handle them.

Conclusion

The create_agents_from_yaml function in Crowe delivers a scalable and production-ready pathway to define, instantiate, and orchestrate intelligent agents directly from a YAML blueprint.

By adhering to the Crowe YAML schema and leveraging the function’s flexible parameters, teams can:

  • Rapidly assemble complex multi-agent orchestrators without hard-coding configurations.

  • Standardize agent behavior across environments while retaining fine-grained control.

  • Seamlessly integrate orchestration patterns that scale from prototypes to full enterprise deployments.

This architecture ensures consistency, extensibility, and operational resilience, making it an ideal foundation for organizations building adaptive, collaborative AI systems at scale.

PreviousCommunication MethodsNextMCP Integrat

Last updated