---
isPublished: true
template: "page.peb"
title: "Dialogue Script Markdown Format v1 — Preview"
displayName: "Dialogue Script Format"
description: "Review and construct iDialogue agent Markdown snapshots with flat YAML settings, authored instructions, Quick Starts and Skills."
category: "resources"
contentType: "reference"
audience: "admin,developer,business-analyst"
tags: "dialogue-script,dlog,markdown,agents,salesforce,process-as-code,coding-agents"
section: "resources"
seoTitle: "Dialogue Script Markdown Format v1"
seoDescription: "Reference the iDialogue agent Markdown export format, instruction sections, Quick Starts, Skill bindings and Salesforce CLI review workflow."
llms: true
llmsSection: "Build Developer"
llmsTitle: "Dialogue Script Markdown Format v1 — Preview"
llmsDescription: "Review or construct .dlog.md agent snapshots: flat YAML settings, authored instructions, Quick Starts, Skill bindings, examples and export-only limits. JSON remains canonical; Markdown import is deferred."
llmsOptional: false
llmsOrder: 20
---

# Dialogue Script Markdown Format v1 — Preview

Dialogue Script presents an iDialogue agent's authored process as one readable Markdown file. Admins and business
analysts can review instructions and process diagrams. Developers can inspect the same content in VS Code or
IntelliJ and retain the snapshot in Git through their existing Salesforce CLI or SFDX Hardis workflow.

Format version 1 is tentatively accepted. Sandbox smoke tests were reported as passing on 12 October 2026.
The current implementation exports a review snapshot. JSON remains the canonical definition for persistence,
published packages, runtime loading and installation by package ID. Markdown import and complete lossless
JSON-to-Markdown-to-JSON conversion remain deferred. Editing or deploying the Markdown Static Resource does not
update or activate the installed agent.

## Start here when using a coding agent

Before reviewing or constructing a Dialogue Script file, fetch this reference through the
[documentation index](/llms.txt) and check the file's `formatVersion`. This page describes `formatVersion: 1`.
Report a documentation gap for other versions instead of assuming the same rules apply.

Repository examples use `.dlog.md`. Salesforce CLI can retrieve the same snapshot as `.markdown` because its
Static Resource content type is `text/markdown`. The file extension does not change these export conventions.

Use the [coding-agent setup guide](/content/build/index.md) for workspace instructions, and the
[agent record reference](/content/build/developer/manage-agent-records.md) for Salesforce authoring concepts.
The [runtime directive reference](/content/agents/DialogueScript.md) describes include, tool and context expansion.
Those directives remain authored text in this snapshot; export does not execute them.

## File layout

| Position | Content | How to read it |
| --- | --- | --- |
| First block | Flat YAML front matter between `---` lines | Available identity, model and binding settings, plus `formatVersion`. |
| Opening body | Root System Instructions | Authored text, including any H1 sections, Mermaid and code fences. |
| Following H1 sections | Related System Instructions | A reused or generated heading, plain `yaml` metadata and authored text. |
| `# Quick Starts` | Default and suggested or Action prompts under H2 headings | User-facing starting prompts, kept separate from System Instructions. |
| `# Skills` | One H2 definition per exported Skill | Readable function bindings and authored description/instructions. |

Use ordinary Markdown headings and plain fenced `yaml` blocks. A `yaml dlog` fence or hidden HTML marker is not
required. Headings inside code fences remain code. Duplicate authored headings are retained.
These conventions describe the emitted snapshot. They do not establish an import grammar or a one-H1-to-one-record
installation rule.

## Front matter

Use one flat key-value mapping. Background settings have names such as `backgroundModel`; they are not nested
under a `background` object. This keeps configuration readable in an IDE front-matter table.

`formatVersion` identifies this file format. `version` is the agent's supplied version; `latestPublishId` is its
supplied package reference. They describe separate things. Available fields are listed below in export order.

| Group | Properties |
| --- | --- |
| Format and identity | `formatVersion`, `name`, `label`, `description`, `version` |
| Model | `provider`, `model`, `maxTokens`, `temperature`, `reasoningEffort`, `verbosity`, `toolChoice`, `convertMarkdown`, `transcriptsEnabled` |
| Context and bindings | `objectType`, `flowName`, `query`, `dataSource`, `dataContextDefinitionId`, `includeRecordData`, `includeRecordMetadata` |
| Background | `backgroundModel`, `backgroundReasoningEffort`, `backgroundVerbosity`, `backgroundToolChoice`, `backgroundTimeout` |
| Package and usage | `latestPublishId`, `packagePostInstallURL`, `corsDomains`, `rateLimit`, `maxTokensPerSession` |

`maxTokens` projects the JSON DTO's `max_tokens`; `toolChoice` projects `tool_choice`. Other listed setting names
follow their DTO names. `name` preserves the configured agent name; `label` preserves a supplied display label.
The exporter does not fill a blank label from the name or invent a setting that is absent from the DTO.

Null values are omitted. Empty strings, `false` and numeric zero are retained. Exported strings are double-quoted;
quotes, backslashes, control characters and line breaks are escaped. Numeric and boolean values keep their types.
Unicode text is supported. A multiline configuration string uses escaped line breaks in its quoted YAML value;
long authored instructions belong in the Markdown body.

The example values below are fixture data, not model recommendations or defaults for a new agent. Root
`isActive` and `displayInAssistant` settings are not exported in this milestone. Activity in instruction or Skill
metadata describes that related record.

## Opening and related System Instructions

The opening text is implicitly the agent's root System Instructions. No extra heading, wrapper or marker is
needed. An author can use multiple H1 sections such as Objective, Instructions, Process Contract and Output Format
within those instructions. Authored text, line endings, Mermaid and code fences are preserved.

Related System Instructions follow in the supplied collection order. Inactive and context-specific records remain
visible for review. An `order` value is displayed as metadata; the exporter does not re-sort by it. Presence in the
snapshot does not mean an instruction is effective in every runtime context.

For each related instruction, the exporter reuses an H1 at the start of its authored text, allowing leading blank
lines. Otherwise it generates an H1 from the label, then the name, then `Instructions`. It places metadata after
that heading and preserves the remaining text. H2 and deeper headings remain prose structure. Additional H1
headings inside the same authored record remain intact.

| Instruction metadata | Meaning |
| --- | --- |
| `key` | The related definition's supplied external ID. |
| `name`, `label` | Supplied identity and display text. |
| `isActive` | The related definition's activity state. |
| `runContext` | Supplied context, such as `All`, `Chat` or `Background`. |
| `order` | Supplied ordering value. |
| `flowName` | A literal Flow binding, if supplied. Export does not run the Flow. |

Salesforce may store instructions in smaller related records. The file remains one readable document; an H1 does
not require a separate Salesforce record. Future import must define how content is partitioned and mapped back to
records. The current export does not provide that mapping operation.

## Quick Starts

A `# Quick Starts` section is emitted when the agent has a nonempty default user prompt or a qualifying related
prompt. The default user prompt appears under `## Default`. Related prompts qualify when they are non-system
prompts marked as suggested or Action prompts. They retain their supplied collection order.

A related Quick Start reuses its leading H2 or generates one from its label, then its name, then `Quick Start`.
Its plain YAML block uses the instruction metadata above and adds supplied `isSuggested`, `isAction` and
`isConfirmation` values. A prompt marked as both system and suggested appears with System Instructions only.

## Skills

The exporter emits `# Skills` when there is at least one Skill. Each Skill has an H2 chosen from its function name,
then its name, then its label, then `Skill`. Definitions retain their supplied collection order, including inactive
Skills. The YAML block is followed by the authored description and instruction text when present.

| Skill metadata | Meaning |
| --- | --- |
| `key`, `name`, `label` | Supplied external ID, name and display label. |
| `functionName` | The configured function name, including a custom alias. |
| `primitiveFunction` | The underlying Skill primitive. It can differ from the function alias. |
| `isActive`, `runContext`, `order`, `version` | Supplied definition state, context, order and version. |
| `flowName` | A literal Flow binding, if supplied. |
| `inputVariables`, `outputVariables` | Supplied string bindings; these are not expanded schemas. |

The Web-to-Lead fixture uses `update_lead` as an alias for the `dml_sobjects` primitive. Select actual primitives
from the [Skills Catalog](/content/support/skills/all.md). These preliminary definitions are not complete Skill
serialization. Runtime-generated tool schemas and steering instructions are not inserted.

## Minimal agent example

This complete example matches the minimal export fixture. Its settings reflect values in the constructed test
agent; omitted fields are absent from that DTO. Copy the contents inside the outer Markdown fence to review the
shape of an exported file.

````markdown
---
formatVersion: 1
name: "Minimal_Agent"
label: "Minimal Agent"
version: 1
provider: "OpenAI"
model: "prime"
maxTokens: 2000
temperature: 0.2
toolChoice: "auto"
convertMarkdown: true
transcriptsEnabled: true
backgroundModel: "gpt-5.1"
backgroundReasoningEffort: "medium"
backgroundVerbosity: "medium"
backgroundToolChoice: "auto"
backgroundTimeout: 600
rateLimit: -1
maxTokensPerSession: -1
---

# Objective

Answer the user's question.
````

## Web-to-Lead example

This complete example matches the Web-to-Lead export fixture. Its Mermaid diagram documents the intended process.
The qualification section illustrates an inactive Background instruction retained for review, and the Skill
bindings illustrate a primitive and a custom alias. IDs and URLs are illustrative placeholders; `pkg-example`
is not an installable package ID and `ctx-w2l` is not a verified destination-org context definition.

````markdown
---
formatVersion: 1
name: "WebToLead"
label: "Web-to-Lead"
description: "Qualify leads and prepare follow-up."
version: 3
provider: "OpenAI"
model: "prime"
maxTokens: 3000
temperature: 0.2
reasoningEffort: "medium"
verbosity: "low"
toolChoice: "auto"
convertMarkdown: true
transcriptsEnabled: false
objectType: "Lead"
flowName: ""
dataSource: "Salesforce"
dataContextDefinitionId: "ctx-w2l"
includeRecordData: true
includeRecordMetadata: false
backgroundModel: "mini"
backgroundReasoningEffort: "high"
backgroundVerbosity: "low"
backgroundToolChoice: "auto"
backgroundTimeout: 300
latestPublishId: "pkg-example"
packagePostInstallURL: "https://example.com/install"
corsDomains: "https://example.com"
rateLimit: 0
maxTokensPerSession: 4000
---

# Objective

Qualify incoming leads and recommend the appropriate follow-up.

# Process Contract

```mermaid
flowchart LR
    A[New Lead] --> B[Validate and match]
    B --> C[Enrich and qualify]
    C --> D[Recommend follow-up]
```

# Lead Qualification

```yaml
key: "w2l.qualification"
name: "LeadQualification"
label: "Lead Qualification"
isActive: false
runContext: "Background"
order: 20
flowName: ""
```

Check spam, detect language and match existing customers.

## Existing Customers

Route support requests to the appropriate Case or Task process.

# Chat Guidance

```yaml
key: "w2l.chat"
name: "ChatGuidance"
label: "Chat Guidance"
isActive: true
runContext: "Chat"
order: 10
```

Ask for the selected Lead before recommending a follow-up.

# Quick Starts

## Default

Summarize the lead and recommend next steps.

## Review This Lead

```yaml
key: "w2l.review"
name: "ReviewLead"
label: "Review This Lead"
isActive: true
order: 0
isSuggested: true
isAction: false
isConfirmation: false
```

Review this lead and explain the recommended next action.

# Skills

## query_sobjects

```yaml
key: "w2l.query"
name: "Query Existing Records"
label: "Match Existing Records"
functionName: "query_sobjects"
primitiveFunction: "query_sobjects"
isActive: true
runContext: "All"
order: 7
version: 2
flowName: ""
```

Find existing Leads, Contacts and Accounts.

Query before recommending creation of another record.

## update_lead

```yaml
key: "w2l.update"
name: "Update Lead"
label: "Save Enrichment"
functionName: "update_lead"
primitiveFunction: "dml_sobjects"
isActive: false
runContext: "Background"
order: 2
version: 4
flowName: ""
inputVariables: "recordId, fields"
outputVariables: "updatedRecord"
```

Save the authorized enrichment and qualification results.

### Restrictions

Preserve existing values unless replacement is explicitly authorized.
````

## Retrieve and review a snapshot

1. Create or revise the agent in Agent Studio, including its authored instructions and Skills.
2. Use the installed version's existing synchronization or publication path to produce the Static Resource.
   Restricting writeback to publication only belongs to a separate publishing milestone.
3. Retrieve the specific resource through Salesforce CLI or the team's existing SFDX Hardis process.
4. Review the Markdown and process diagram in VS Code or IntelliJ, compare the Git diff, and commit through the
   team's approved review workflow.
5. Continue installing agents through the JSON package-ID workflow.

The Static Resource name stays `AI_Agent_<sanitized agent Name>`. It uses the agent name, not the display label.
Namespace matching and create/update behavior are retained, with private cache control and `text/markdown` content.
For an agent named `WebToLead`, the source files normally appear as `AI_Agent_WebToLead.markdown` and
`AI_Agent_WebToLead.resource-meta.xml`; a namespace may be part of the resource's full name in the org.

Substitute the actual resource full name and your sandbox alias:

```bash
sf project retrieve start \
  --metadata "StaticResource:<actual-resource-full-name>" \
  --target-org <sandbox-alias>
```

The companion metadata and retrieved filename are authoritative. If a previous JSON export exists in the local
project, review its obsolete sibling before retaining the new snapshot in Git. Snapshot writeback is best effort;
a failed export does not invalidate the saved canonical JSON agent.

## Supported limits and future work

- The snapshot omits files, memories, evaluations, trigger definitions, working-status definitions and nested
  Skill settings. Top-level org/record IDs, runtime state and unlisted settings are also omitted.
- Credential properties and generated runtime tool definitions are excluded. Authored text is retained as supplied;
  review that text before sharing a snapshot.
- Flow names, Data Context IDs, package references and other bindings remain literal references. Export does not
  bundle dependencies, verify those references or remap them to another org.
- Runtime context assembly, include expansion and active/context filtering do not run during export.
- Markdown import, validation/build tooling, complete Skill serialization and lossless conversion remain future
  milestones. A Markdown deployment alone does not install or promote an agent.

This reference describes the implemented export contract. It does not declare an executable AGENTS.md standard or
add instructions to a coding workspace automatically. Teams can use the coding-agent guide to add a reference to
their existing workspace instructions.

Implementation story: Dialogue Script Markdown Static Resource (`stories/DialogueScriptFormat.md` in the iDialogue
API repository). The related publishing story controls future writeback timing and runtime package loading.