Dialogue Script

Dialogue Script

Dialogue Script (also referred to as dlog script or agent script) is the Markdown-first DSL that powers iDialogue’s agent system prompts. It lets authors compose reusable instructions enriched with dynamic tool manifests, reusable prompt fragments, and future context directives without leaving Markdown.

Author Experience at a Glance

Dialogue scripts are processed automatically on the first request for a dialogue session. The resulting Markdown (with expanded tools and includes) becomes the systemMessage used for the OpenAI call, and any resolved tool definitions are attached to the agent instance for that session.

Runtime Pipeline

If any required directive fails to resolve (missing tool, include, or manifest), processing stops with an error and the request is rejected.

Tag Reference

<tool_definition />

Tool definitions declare which OpenAI function tools should be available to the agent during the initial request.

Behavior notes:

• Invalid primitive values surface as script errors that identify the missing tool key.
• After <include-tools> expands, the processor re-parses tool definitions before resolution so manifest-generated tools are included.
• Resolved content replaces the original tag verbatim; there is no passthrough copy of the original XML-style tag.

Example

<tool_definition primitive="describe_sobjects" />
<tool_definition primitive="query_sobjects" name="query_orders" />

<include />

Includes splice reusable Markdown fragments into the dialogue script. They are resolved by source-type specific resolvers.

Built-in Resolvers

When required="false" and an include fails to load, the engine substitutes fallback (or nothing if omitted) and continues.

Example

<include
  name="Rooms Agent Base Prompt"
  src="rooms__AIModel__c"
  srcType="agent-prompt"
  required="false"
  fallback="<!-- Prompt unavailable; proceed with default behavior. -->"
/>

<include type="system" name="..." />

Declares a system agent for the session. This tag is handled before the Dialogue Script processor runs and is not resolved by the standard include resolver. The tag is replaced inline with the system agent prompt block (system prompts, system AIPrompt entries, and tool include tags).

Notes:

• name is the system agent key (managed package API name like rooms__AIModel__c).
• Only the first system include is honored; additional system tags are removed.
• Legacy <include systemAgent="..."/> syntax is not supported.

Example

<include type="system" name="rooms__AIModel__c" />

<include-tools />

Tool includes pull JSON manifests that describe one or more tools, then emit <tool_definition /> tags for each entry.

Default Manifest Resolver (agent-tool)

• Resolves {src}.tools.json from the tenant’s agent tool manifest library (shares configuration with the prompt library).
• Manifest format accepts either:
  • an array of objects: [{"primitive":"describe_sobjects","name":"describe_sobjects"}]
  • or an object with defaultTools and/or tools arrays.
• Each entry must provide primitive; name is optional.
• Entries render as <tool_definition primitive="…" name="…" /> prior to the tool resolution step.

Example Manifest

[
  { "primitive": "describe_sobjects" },
  { "primitive": "query_sobjects", "name": "query_contacts" }
]

Example Tag

<include-tools src="rooms__AIModel__c" srcType="agent-tool" required="false" />

If the manifest is missing and required="true" (default), processing stops with an error.

rooms__ namespace fallback

Tool manifests that follow the managed-package namespace (src="rooms__Something__c") are treated as optional even when required is omitted. If the resource is not found, the <include-tools> tag is simply removed and no tool definitions are emitted so system agents can continue bootstrapping while the per-object manifest is authored.

<context />

Context directives resolve Data Context Definitions (DCDs) and replace themselves with a Markdown block containing H2 sections in this order:

1. Definition (the raw DCD)
2. Queries (executed SOQL with row counts/truncation)
3. Context (resolved data payload)

This order is intentional so agents see how data was retrieved before consuming the data itself.

Inline JSON takes precedence over key. When a JSON body is present, the processor uses it as the DataContextDefinition.

Example (key-based)

<context name="Opportunity Quote" key="ctx-data-def:0fbba893501f462d969c549dae609efd" recordId="006xx000004TMiTAAA" />

To aid troubleshooting, enable pretty JSON:

<context name="Opportunity Quote" key="ctx-data-def:0fbba893501f462d969c549dae609efd" recordId="006xx000004TMiTAAA" pretty="true" />

Limit output to a single section when needed:

<context name="Opportunity Quote" key="ctx-data-def:0fbba893501f462d969c549dae609efd" recordId="006xx000004TMiTAAA" include="definition" />

Example (inline definition)

<context name="Opportunity Quote" recordId="006xx000004TMiTAAA">
  {"version":"1.0","mode":"record","master":{"objectApiName":"Opportunity","alias":"opportunity"},"datasets":[]}
</context>

When processed, the <context> tag is replaced inline with the H2 sections listed above. Each section contains a JSON block.

Sample Script

# Concierge Agent

You are the concierge for iDialogue’s Rooms product. Welcome visitors, gather their needs, and guide them to the right resources.

<include type="system" name="rooms__AIModel__c" />

<include name="Mission Statement" src="company_mission" srcType="agent-prompt" required="false" fallback="Mission statement currently unavailable." />

<include-tools src="rooms__AIModel__c" />

<context name="VisitorIntake" key="ctx-data-def:example" recordId="006xx000004TMiTAAA" />

Always return concise, friendly answers. Confirm contact details before creating follow-up tasks.

When processed, the script above yields fully expanded tool descriptions, inlines the mission statement Markdown (if present), and records the context directive for downstream consumers.

Posting Dialogue Scripts to the iDialogue API

Use the standard AI response endpoint and place the script in the systemMessage field of the chat request. The processor runs automatically on the initial dialogue turn.

curl -X POST https://{tenant-host}/api/openai/response \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
        "orgId": "00Dxx0000000001",
        "dialogueId": "dlg-12345",
        "agentId": "a0Oxx0000000001",
        "model": "gpt-4o-mini",
        "systemMessage": "# Concierge Agent\n\n<include type=\"system\" name=\"rooms__AIModel__c\" />\n<include-tools src=\"rooms__AIModel__c\" />\n",
        "userMessage": "Hi there!",
        "convertMarkdown": true
      }'

Recommendations for production use:

• Generate unique dialogueId/requestId pairs per session to unlock caching and polling behavior.
• Ensure optional includes/manifests declare required="false" when referencing tenant-specific assets that may not exist in every org.
• When updating shared manifests or prompt snippets, publish them once in the agent prompt library and reuse via <include>/<include-tools> tags rather than inlining copies.

Troubleshooting Checklist

• Missing tool or prompt → Confirm the asset exists in the configured prompt or tool manifest library and the logical key contains only letters, numbers, or underscores.
• Unexpected raw tags in the final prompt → Verify processing only occurs on the initial request. Subsequent turns reuse the cached instructions.
• System agent include not applied → Ensure the tag uses type="system" with a valid name and that the request is the initial turn.
• Mode errors on includes → Only mode="replace" is implemented. Other values parse but do not enable append/prepend yet.
• Context resolution errors → Verify key or inline JSON is provided, recordId is a valid 18-character Id for record-scoped contexts, and the DCD exists in Redis. Use required="false" to soft-fail and continue.

For roadmap updates or resolver customizations, subscribe to the Dialogue Script release notes or contact the iDialogue platform team.