ADL Reference Manual

Complete documentation of the Assistant Description Language

ADL Reference Manual

This document describes the components of the Assistant Description Language (ADL) and how to use it to define an AI assistant. It includes:

The general structure of ADL.
The metadata and assistant_instructions sections.
The mandatory nature and purpose of each property.
Concrete examples in YAML.

General Structure of ADL

The ADL file consists of two main root-level properties:

1 metadata required

2 assistant_instructions required

Both properties are mandatory for the ADL to be valid and functional.

Section `metadata`

Type: object

Required: Yes

Purpose:

Provides descriptive information and authorship about the assistant, including author's name, organization, license, etc.

The metadata section contains several properties, of which two are mandatory: author and description. The others are optional but recommended for maintaining history or defining visibility and usage rights.

`metadata.author`

Type: object
Required: Yes
Purpose: Indicates the creator of the assistant (and, optionally, contact information and role).
Properties:
- name (required, type string): author's name.
- role (optional, type string): role or position.
- contact (optional, type string): contact information.
- organization (optional, type string): associated institution or company.

Usage example:

author:
  name: "Jane Doe"
  role: "AI Developer"
  contact: "jane.doe@example.com"
  organization: "OpenAI Spain"

`metadata.description`

Type: object
Required: Yes
Purpose: Provides the general description of the assistant (title, summary, etc.).
Properties:
- title (required, type string): main title.
- summary (required, type string): description or short summary.
- coverage (optional, type string): main purpose of the assistant.
- educational_level (optional, array of string): suggested educational levels.
- use_cases (optional, array of string): usage scenarios.
- keywords (optional, array of string): keywords.

Usage example:

description:
  title: "Language Assistant"
  summary: "Helps practice conversation and grammar."
  coverage: "English"
  educational_level:
    - "Secondary Education"
  use_cases:
    - "Listening practice"
    - "Text revision"
  keywords:
    - "languages"
    - "education"

`metadata.visibility`

Type: object
Required: No
Purpose: Defines whether the assistant is public or private.
Property:
- is_public (type boolean)

Usage example:

visibility:
  is_public: true

`metadata.rights`

Type: string
Required: No
Purpose: Indicate licenses or usage restrictions.

Example:

rights: "CC BY-NC 4.0"

`metadata.creation_date` and `metadata.last_update`

Type: string
Required: No
Purpose: Record the creation date and last modification.

`metadata.history`

Type: array of string
Required: No
Purpose: Keep a history of changes or versions.

Section `assistant_instructions`

Type: object

Required: Yes

Purpose:

Defines the behavior logic, style, capabilities, and tools for the assistant.

Includes the following required properties:

context style_guidelines final_notes help_text role behavior capabilities tools

`assistant_instructions.context`

Type: object
Required: Yes
Purpose: Describe the context and user data handling.
Required properties:
- context_definition (array of string)
- integration_strategy (array of string)
- user_data_handling (array of string)

Example:

context:
  context_definition:
    - "The assistant resolves programming questions."
    - "Intermediate level users."
  integration_strategy:
    - "Integration with online code editor."
    - "Snippets repository API."
  user_data_handling:
    - "No personal data is stored."
    - "Complies with GDPR regulations."

`assistant_instructions.style_guidelines`

Type: object
Required: Yes (although its internal properties are optional)
Purpose: Set the tone and format of responses.
Optional properties:
tone level_of_detail formatting_rules

Example:

style_guidelines:
  tone: "Formal and didactic"
  level_of_detail: "Detailed with examples"
  formatting_rules:
    - "Use bullets for steps"
    - "Highlight keywords in bold"

`assistant_instructions.final_notes`

Type: array of string
Required: Yes
Purpose: Global notes or reminders.

Example:

final_notes:
  - "Check spelling before responding."
  - "Do not provide medical or legal advice."

`assistant_instructions.help_text`

Type: string
Required: Yes
Purpose: Message displayed when the user requests help.

Example:

help_text: "Type /help to see available commands."

`assistant_instructions.role`

Type: string
Required: Yes
Purpose: Define the personality or role (for example, "Expert Assistant").

`assistant_instructions.behavior`

Type: object
Required: Yes
Purpose: Describes the assistant's reactions in different situations.
Required properties:
- invalid_command_response (string)
- on_greeting (array of string)
- on_help_command (array of string)
- unrelated_topic_response (string)
- prompt_visibility (string)

Example:

behavior:
  invalid_command_response: "Sorry, I don't recognize that command."
  on_greeting:
    - "Hi! How can I help you?"
    - "Happy to help you today."
  on_help_command:
    - "List of commands: /explain, /example, /test."
  unrelated_topic_response: "I don't have information about that topic."
  prompt_visibility: "hidden"

`assistant_instructions.capabilities`

Type: array of string
Required: Yes
Purpose: List of main capabilities of the assistant.

Example:

capabilities:
  - "Provide code examples"
  - "Explain algorithms"

`assistant_instructions.tools`

Type: object
Required: Yes
Purpose: Defines the commands, options, and decorators that the assistant can use.
Required properties: commands, options
Optional property: decorators

`assistant_instructions.tools.commands`

Type: object
Required: Yes
Purpose: Each command is an object with display_name, description, and internal_description.

Example:

commands:
  explain:
    display_name: "/explain"
    description: "Provides a detailed explanation."
    internal_description: "Level adapted to the user."
  example:
    display_name: "/example"
    description: "Shows a code example."
    internal_description: "Includes comments."

`assistant_instructions.tools.options`

Type: object
Required: Yes
Purpose: Parameters that complement the commands.

Example:

options:
  language:
    display_name: "--language"
    description: "Define the programming language (Python, JavaScript, etc.)"
    internal_description: "Default: Python."
  difficulty:
    display_name: "--difficulty"
    description: "Level: basic, intermediate, or advanced."
    internal_description: "Default: intermediate."

`assistant_instructions.tools.decorators` (optional)

Type: object
Required: No
Purpose: Add "tags" or additional modifications to the output.

Example:

decorators:
  highlight:
    display_name: "@highlight"
    description: "Highlights important text."
    internal_description: "Used to draw attention."

Complete ADL Documentation

This reference manual contains all the properties and structures needed to create effective assistants with the Assistant Description Language.

Back to ADL

General Structure Section metadata

metadata.author metadata.description metadata.visibility metadata.rights metadata.creation_date metadata.history

Section assistant_instructions

assistant_instructions.context assistant_instructions.style_guidelines assistant_instructions.final_notes assistant_instructions.help_text assistant_instructions.role assistant_instructions.behavior assistant_instructions.capabilities assistant_instructions.tools

ADL Reference Manual