# 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

```python
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).\
  &#xNAN;_&#x45;xample:_ `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.\
  &#xNAN;_&#x45;xample:_ `"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

```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.
