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 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 for workspace instructions, and the agent record reference for Salesforce authoring concepts. The runtime directive reference describes include, tool and context expansion. Those directives remain authored text in this snapshot; export does not execute them.

File layout

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.

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.

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.

The Web-to-Lead fixture uses update_lead as an alias for the dml_sobjects primitive. Select actual primitives from the Skills Catalog. 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.

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

---
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:

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.