Why we built YAML config alongside the visual builder

Most AI agent platforms pick one configuration model. Either visual (drag and drop, no code) or code-based (Python, JSON, YAML).

Avery NXR has both. The visual builder is the primary surface. YAML is the escape hatch.

This was a deliberate choice that took longer to build than picking just one. Here's why we did it.

The two audiences

When we surveyed potential users, we found two distinct profiles:

Profile A — Non-technical operator. A marketing lead, ops manager, hiring manager, customer success leader. Confident with software. Not a programmer. Wants to build agents but doesn't want to write code.

For Profile A, visual builder is essential. Drag, drop, connect, configure. The visual builder is the product.

Profile B — Power user / engineer. A technical founder, ops engineer, software engineer who happens to need an agent platform. Comfortable with config files. Wants version control, code review, programmatic configuration.

For Profile B, visual builder is limiting. They want to see and edit the actual config. Diff it. Commit it to git. Apply it across environments.

Most agent platforms force one profile to use the other's tools. Visual-only platforms frustrate engineers. Code-only platforms exclude operators.

We thought we could serve both.

How the dual model works

Every Avery NXR agent has a YAML configuration file. The visual builder reads and writes this file.

When you drag a "send email" node into the visual builder, the YAML file gets a send_email step. When you configure a trigger, the YAML file gets the trigger config. When you change the model selection, the YAML file gets the model name.

The visual builder is a UI on top of YAML. The YAML is the source of truth.

This means:

→ Non-technical users can build everything in the visual builder. They never see the YAML.

→ Power users can edit the YAML directly. The visual builder reflects their changes.

→ Mixed teams can collaborate. The marketing lead drags the agent in the visual builder. The engineer reviews and tweaks the YAML. Both edits go to the same file.

→ CI/CD workflows become possible. Power users can commit agent YAML files to git, review changes, deploy via automated pipelines.

What's in an agent YAML

Roughly, the YAML structure looks like:

agent:
  name: customer-support-triage
  model: qwen2.5-coder:7b
  trigger:
    type: inbox
    source: support@example.com
    filter: ...
  steps:
    - id: classify
      type: llm_classify
      prompt: ...
    - id: route
      type: conditional
      conditions: ...
    - id: respond
      type: send_email
      ...
  safety:
    confidence_threshold: 0.7
    high_stakes: false
    audit: enabled

It's readable. Engineers can scan it and understand what the agent does. Reviewers can comment on specific lines. Diffs are meaningful.

This is the kind of artifact that integrates into existing engineering workflows. Pull requests can be reviewed for agent configuration changes the same way they're reviewed for code changes.

What the visual builder makes easier

The visual builder isn't just a "skin" over YAML. It does real work:

→ Type-aware drag-and-drop. When you drag a "send email" node, it knows what fields are required and prompts for them. YAML doesn't enforce this at edit time.

→ Connector authentication flow. Clicking "connect Gmail" launches OAuth flow. In YAML, you'd reference the connection by name (which you set up via UI).

→ Real-time validation. Visual builder shows errors immediately. YAML validation runs at parse time, less interactive.

→ Discovery. Visual builder shows you what's possible (drag a node from the sidebar). YAML requires you to know the node types exist.

→ Reordering steps visually. Easy in the builder. Possible in YAML but more cognitively expensive.

For non-engineers, the visual builder removes barriers that would otherwise make agent building inaccessible.

What the YAML makes easier

YAML enables things the visual builder can't, or can't easily:

→ Bulk operations. Search and replace across 20 agents to update a connector reference. Painful in visual builder. Trivial in YAML.

→ Version control. Git history of agent changes. Code review for agent updates. Rollback. None of this works as well with visual-only platforms.

→ Programmatic generation. Build a script that generates agent YAML based on inputs (customer name, role title, etc.). Useful for templating across customers.

→ CI/CD. Deploy agents through automated pipelines. Test in staging. Promote to prod.

→ Backup and migration. Export YAML files. Move agents between Avery NXR installs. Share configurations.

For engineering teams, the YAML enables workflows that the visual builder alone can't support.

What this costs us in product complexity

Maintaining both surfaces is harder than picking one:

→ Every feature must work in both. Add a new step type? Implement in visual builder + YAML schema + executor. Three places, not one.

→ Synchronization. When YAML changes, visual builder must reflect it. When visual builder changes, YAML must update correctly. Edge cases get tricky.

→ Documentation. Two paths to document. Some users need visual-builder tutorials. Others need YAML reference.

→ Testing. Edits in either surface must produce equivalent results. Test matrices double.

These costs are real. We've paid them because the audience expansion is worth it.

The platforms that picked one

We've watched competitors pick one model:

Visual-only platforms (some of the major cloud agent platforms): Great for non-engineers. Lose engineers as customers. Engineers either build custom infrastructure or pick a code-first platform.

Code-only platforms (CrewAI, LangChain, AutoGen): Great for engineers. Lose non-engineers entirely. The TAM is much smaller than for visual platforms.

Picking one is a clean choice. It also forces the platform into a single audience.

Why dual surfaces matter for adoption pattern

We covered the bottom-up adoption pattern in [post 160]. Champions install free tier, build personal use cases, bring to teammates, expand to team adoption.

The dual config model supports this pattern:

→ Champion (often an engineer) installs and builds first agents. They might use YAML directly because they're comfortable with it.

→ Champion shares with teammate (often non-engineer). Teammate uses visual builder to understand existing agent. They tweak via visual builder.

→ Mixed team collaborates. Engineer's YAML edits + non-engineer's visual edits both update the same agent. Nobody is blocked.

If we'd picked one surface, this collaboration pattern would break. Either the engineer would feel constrained (visual-only) or the non-engineer would feel excluded (code-only). Both surfaces means both can contribute.

The technical implementation

For curious technical readers: the visual builder is a React app that renders a YAML file as a node graph. Edits in the visual builder update an in-memory representation, which gets serialized back to YAML on save. The YAML file is the persistent source of truth.

The agent runtime reads YAML files directly. It doesn't care whether the YAML was hand-written or generated by the visual builder. Both paths produce equivalent agents.

For YAML edits to be reflected in the visual builder, we parse and re-render. Edge cases (malformed YAML, unsupported step types from manual edits) show warnings but don't crash.

What this means for your team

If you're evaluating Avery NXR with a mixed team:

→ Non-technical folks start with the visual builder. Quick onboarding, no code required.

→ Technical folks can work in YAML directly when they want power-user workflows.

→ Both can contribute to the same agents. Collaboration friction is low.

If you're evaluating Avery NXR as a solo engineer:

→ You can use YAML directly. You'll find the visual builder useful for discovery + occasional tweaks but won't depend on it.

→ Your agent configs go in git like any other code artifact.

If you're evaluating Avery NXR as a solo non-engineer:

→ You can use the visual builder exclusively. You'll never need to touch YAML unless you choose to.

→ When you eventually want to share agents with engineers on your team, the YAML path enables that.

The principle

Software products that serve mixed-audience use cases need to support multiple skill levels gracefully. The instinct to "pick one and be best at it" often leaves valuable user segments excluded.

We picked dual surfaces because the audience for AI agent platforms is structurally mixed — operators want visual, engineers want code, teams have both.

It cost more to build. We think it's worth it.

→ avery.software — Free Desktop tier. Visual builder + YAML. Use whichever fits your hand.