Agents

An Agent definition is one YAML file per Agent, in agents/. To see a complete, valid project whose Agent binds an MCP Tool, an OpenAPI Tool, a Knowledge Base and a Data Table, run npx @elizon/cli example agent (offline, no account).

name: Specialist
description: 'Answers the request once it is well understood.'
status: active
configSchemaVersion: 1
llm:
  slot: reasoning
  modelPreference: null
tools: []
config:
  basic:
    include_agent_name: true
    include_datetime: false
  model:
    primary:
      llm_slot: reasoning
      model_id: null
      temperature: 0.7
      max_output_tokens: 4096
    secondary:
      enabled: false
      llm_slot: null
      model_id: null
      temperature: 0.7
      max_output_tokens: 4096
  memory:
    enable_user_memory: false
    enable_agentic_memory: false
    session:
      add_history_to_context: true
      history_runs: 3
      read_chat_history: true
      session_summary: false
      session_state: false
      session_state_schema: null
  instructions:
    content: |
      You answer the request that intake has clarified.
      Be specific, and say when you are not sure.
  knowledge:
    agentic_rag: true
    metadata_filter: false
    knowledge_bases: []
  reasoning:
    mode: 'off'
    effort: medium
    max_steps: 5
    expose: internal
  advanced:
    enable_markdown: true
    enable_structured_output: false
    structured_output_schema: null
    retries: 0
    retry_delay_seconds: 1
    exponential_backoff: false
    enable_tracking: true
    enable_logging: true

The fields that matter most

The settings correspond to the Agent editor in Studio. Everything is carried except what identifies an Organization: model ids come from the installer's Slot, and Tools and Knowledge Bases are wired to the resources the same install creates. Every field is described below.

Top-level fields

status

Install creates the Agent with the status you write, and nothing in the install changes it.

Tool bindings

tools: lists what the Agent may call. Each entry is one binding: one operation of one thing. There are four kinds, and the keys tell them apart: a binding has tool, app or table, never two of them.

toolType is written only on a Tool binding, and only as mcp or swagger. The installed binding's tool type is app for an app operation and data_table for a Data Table action, but you never write those: a binding with toolType: app or toolType: data_table is refused by build.

Every binding has:

• enabled (true or false, required): false travels as written, so the installed Agent has the binding switched off until the operator turns it on in Studio.
• config (required, {} for nothing): see Binding config.

MCP and OpenAPI operations

tools:
  # An MCP tool, named exactly as the server lists it.
  - tool: tools.calendar
    toolType: mcp
    actionId: list_availability
    enabled: true
    config: {}
  # An OpenAPI operation, named by its operationId in the spec.
  - tool: tools.orders
    toolType: swagger
    actionId: getOrder
    enabled: true
    config: {}

Bind the same Tool once per operation the Agent should have. Two bindings of the same Tool and actionId are refused (duplicate binding). The Tool file formats, and how build derives an OpenAPI actionId, are on Tools.

App operations

An app operation is one operation of an app ELIZON ships (Google Calendar, Google Contacts, Google Drive, Google Sheets, Gmail), run as the operator's own connected account.

tools:
  - app: google-calendar
    resource: availability
    operation: free-busy
    credential: calendar-account
    enabled: true
    config:
      param_overrides:
        # The model cannot choose another calendar: this value always wins.
        - name: calendarIds
          value: [primary]

compliance:
  providers: [google]
slots:
  - id: calendar-account
    type: credential
    scheme: oauth2
    app: google
    required: true
    description: The Google account whose calendar the Agent reads.

Rules that apply at install:

• credential: null, or a Slot the operator leaves for later: the Agent is installed without this tool. Nothing fails; the Package's page lists the open Slot.
• A Slot bound to a vault secret instead of a connected account is refused: an app operation runs as an account.
• Gmail is offered only on an ELIZON whose operator has turned it on; elsewhere the install is refused.
• An operation that answers with a file, or needs a file, cannot be an Agent tool: use it in a Workflow.
• List the app's provider (google) in compliance.providers. validate warns when it is missing.
• An operation that cannot be undone (deleting an event) tells the model so in its description, and a description_override cannot remove that sentence.

Two bindings of the same operation through the same credential Slot are refused; the same operation through two different Slots is two accounts and is allowed.

Data Table actions

A Data Table binding gives the Agent one action on one of the Package's tables.

tools:
  # Reads.
  - table: dataTables.customers
    actionId: rows.get
    enabled: true
    config: {}
  - table: dataTables.customers
    actionId: rows.exists
    enabled: true
    config: {}
  - table: dataTables.customers
    actionId: rows.lookup
    enabled: true
    config: {}
  # Writes. Each one is a separate decision.
  - table: dataTables.customers
    actionId: rows.insert
    enabled: true
    config: {}
  - table: dataTables.customers
    actionId: rows.update
    enabled: true
    config: {}
  - table: dataTables.customers
    actionId: rows.upsert
    enabled: false
    config:
      description_override: Records a customer, adding the row if the customer number is new.

The opt-in rules:

• One table and one action per binding. Bind a table once per action the Agent should have.
• A write needs its own binding. The Agent can write only through an enabled binding for exactly that table and that action; a read binding never lets it write.
• There is no delete. A binding that names any other actionId is refused by build, at install, and again when the Agent calls it. To delete rows, use a Workflow's Data Table node.
• A write tells the model it changes data, and a description_override cannot remove that.

The per-call bounds (rows returned, values looked up, rows written) and what each action answers are on Data Tables → Agent tool bindings.

Binding config

Every binding's config takes the same three keys, all optional. {} sets none of them.

tools:
  - tool: tools.orders
    toolType: swagger
    actionId: listOrders
    enabled: true
    config:
      description_override: Lists the open orders. Use it before you promise a delivery date.
      param_overrides:
        - name: status
          value: open

Any other key in config is refused by build.

Skills

skills: lists the Skills the Agent uses, each as skills.<name>, where <name> is a skills[] entry in the same elizon.yaml. Install attaches each one to the Agent, as the Agent's Skills section in Studio does. Leave the key out, or write [], for an Agent that uses none.

skills:
  - skills.price-calculation

• A name the manifest does not declare is refused by validate and build: `agents.price-assistant` references `skills.nope`, which is not declared in this Package.
• Each entry must be skills.<name>. A bare name, another collection (tools.x) or the same Skill twice is refused by build.
• Only a Skill of the same Package can be listed. An Organization's own Skills cannot be referenced.
• An Agent that lists Skills needs compatibility.minPlatformVersion: 0.25.0 or newer in elizon.yaml. validate and build refuse a lower value. See Package manifest.
• Exporting an Agent from Studio writes only the attached Skills that are in the same export. An attached Skill left out of the export is left out of skills too, without a warning: the Agent then ships without it.
• When the operator installs onto one of their own Agents instead of the Package's, install adds the listed Skills to that Agent, and uninstalling removes only the attachments the install added. Skills the operator had already attached stay.
• An update attaches the Skills the new version lists, and uninstalling the Package removes the Agent's attachments with the Agent.
• The installed Skill is a draft: the operator activates it in Studio (after the scan, and the approval if it asks for tools) before the Agent can load it. See Skills.

Name the Skill in the Agent's instructions too, so the Agent knows when to use it.

The config block

config is what the Agent editor in Studio sets, field by field. Write every section, as the examples do: install creates the Agent with the config you wrote and does not fill in a section you left out. build checks every value you write against the rules Studio saves an Agent under, so a value Studio would refuse (reasoning.max_steps: 40) is refused at build, not after install.

The Default column is what a new Agent gets in Studio, a reasonable starting value.

Three names differ from the stored Agent, because the stored ones identify the source Organization: the portable model.primary.llm_slot and model.secondary.llm_slot are stored as llm_config_id (the operator's Configuration, resolved at install); a Knowledge Base binding's knowledge_base is stored as kb_id plus the installed Knowledge Base's name; and instructions.template_id (a pointer into the source Organization's prompt library) is never carried, because the template's text is already in instructions.content. Write the portable names.

basic

model

memory

instructions

knowledge

config:
  knowledge:
    agentic_rag: true
    metadata_filter: false
    knowledge_bases:
      - knowledge_base: knowledgeBases.product-docs
        max_results: 5
        hyde_retrieval: false

reasoning

How each mode behaves when the Agent also has tools (skills, Knowledge Bases, Tools):

• off or scratchpad: if the model refuses tools because it reasons by default, the run is retried once without reasoning, and ELIZON remembers that for the model, so later runs send that setting from the start. A second refusal fails the run with the provider's message.
• native on OpenAI: the run uses OpenAI's Responses API, which accepts a reasoning effort and tools together. On any other provider, Azure OpenAI and OpenAI-compatible endpoints included, nothing changes.

advanced

config:
  advanced:
    enable_markdown: false
    enable_structured_output: true
    structured_output_schema:
      type: object
      properties:
        category: { type: string, enum: [billing, delivery, other] }
      required: [category]
    retries: 2
    retry_delay_seconds: 2
    exponential_backoff: true
    enable_tracking: true
    enable_logging: true

Combinations a provider can refuse

Some models reason by default, even with reasoning.mode: 'off', and their provider refuses function tools unless it is told not to reason. Any Agent with tools (a Knowledge Base, a skill, a Tool, an app operation or a Data Table action) can meet this. ELIZON retries such a run once and remembers the model; native mode on OpenAI uses the Responses API instead. If it still fails, the run ends with the provider's message, which reads like:

Function tools with reasoning_effort are not supported for <model> in /v1/chat/completions.
To use function tools, use /v1/responses or set reasoning_effort to 'none'.

What happens in each mode, and why a streamed run (/run-stream) reports the first refusal as an error event instead of retrying it, is in Agents → Reasoning and tools. Nothing in the Package can prevent it: which models reason by default is the provider's choice, so the fix, if one is needed, is the operator's choice of model.

Wiring

• Reference the Agent elsewhere as agents.<manifest-name>: in a Team's members, a Workflow's ai_agent node, a voice configuration, or as the entry point.
• Any Slot the Agent uses can list it in boundTo, so the installer sees which answer affects it.
• Install order guarantees the Agent's Tools, Skills, Knowledge Bases and Data Tables exist before the Agent does.