DSL

What is DSL?

DSL is a YAML configuration format that represents an Agent’s full setup, including (depending on type):

• metadata (name, description, tags, icon)

• prompts / instructions

• flows (ChatFlow / JobFlow)

• tools and tool parameters

• variables and bindings

• model configuration

• optional capabilities (e.g., file upload, voice)

DSL enables “configuration as code”:

• easy backups

• easy replication across workspaces

• reviewable changes in Git

• shareable templates inside your team

---

Where You Can Use DSL

1) Create from DSL (Agent & Multi-Agent)

When creating a new Agent (or Multi-Agent), you can choose Create from DSL to bootstrap everything from a YAML file.

2) Export DSL (Draft)

From the Agent editor, you can export the current Draft as DSL.

3) Export Config (Published Version)

From Version History, you can export DSL for a specific published Version using Export Config.

4) Import DSL (into an Agent)

You can import a DSL file to load configuration into an Agent.

📌 Important: Depending on your product behavior, importing may:

• overwrite the current Draft, or

• create a new Agent from the DSL

In this doc, label the behavior exactly as your UI works. If import overwrites Draft, say it explicitly.

---

Supported Agent Types

DSL supports:

• Instruction Agents (system prompt + tools + variables)

• ChatFlow Agents

• JobFlow Agents

• Multi-Agents

The DSL kind field indicates which type it represents (examples below).

---

DSL Structure Overview

Top-level fields

Most DSL files follow this structure:

• kind: the resource type (e.g., instruction, chatflow, jobflow, multi-agent)

• version: DSL schema version (e.g., 1.0.0)

• metadata: identity and display info (name, description, icon, tags, timestamps)

• spec: the functional definition (prompts, flows, nodes, etc.)

• model_config: model/provider and generation parameters

• tools: enabled tools and their parameter schemas/settings

• optional: abilities, datasets, extend_properties (platform-dependent

---

Create from DSL (Step-by-step)

1. Go to Workforce Factory → Agent (or Multi-Agents)

2. Click Create from DSL

3. Paste or upload your DSL YAML

4. Confirm → the system creates an Agent with:

   • prompts/flows

   • tools

   • variables

   • model config

5. Review the created Draft

6. Publish when ready

---

Export DSL (Draft)

Use this when you want to:

• backup work-in-progress

• share a configuration with teammates

• commit configuration to Git for review

Steps

1. Open the Agent editor

2. Click Export as DSL (or equivalent)

3. Save the YAML file

📌 Reminder: this exports the current Draft (which may not be published yet).

---

Export Config (Version) — For Auditing & Releases

Use Export Config from Version History when you want a DSL file that represents an immutable released snapshot.

Steps

1. Open the Agent editor

2. Open Versions panel

3. Choose a version → click ⋯ → Export Config

4. Save the YAML file

This is the best option for:

• compliance

• production reproducibility

• release backups

---

Import DSL (Step-by-step)

Steps

1. Open an Agent editor (or creation page, depending on UI)

2. Click Import DSL

3. Paste/upload YAML

4. Confirm import

📌 Behavior to document clearly (choose the one that matches your UI):

• Option A — Import overwrites Draft: Import replaces your current Draft configuration.

• Option B — Import creates a new Agent: Import generates a new Agent and leaves the original untouched.

---

Best Practices

Keep DSL in source control

Store exported DSL files in Git to:

• track changes over time

• review with PRs

• compare version snapshots

Use Version export for production baselines

For production releases, export from Versions → Export Config so the artifact matches the published state.

Avoid secrets in DSL

Do not store API keys or secrets in plaintext DSL files.

• Use workspace secrets / credentials management (if available)

• Reference secrets by name/ID instead of embedding values (recommended)

Watch for portability differences

When importing DSL into another workspace:

• tool availability may differ

• knowledge bases/datasets may not exist

• icon URLs must be accessible

• referenced agents/resources may need remapping

---

Troubleshooting

Import fails due to schema mismatch

• Check version field in DSL

• Export a fresh DSL from a working agent and compare structure

Tools missing after import

• Confirm the destination workspace has the same tools enabled

• Check tool parameter schemas (required fields)

Variables not bound correctly

• Ensure variable keys match the placeholders used in prompts/flows

• Rebind variables in the editor if needed

---