AI steps

AI steps let workflows call a large language model (LLM) for reasoning, classification, summarization, or agent-driven execution.

AI steps can also manage Elastic Agent Builder conversations:

• Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Create a conversation.
• Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Add notes and user messages to a conversation without triggering an agent response.
• Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. Read and update a conversation's attachments and metadata.

The ai.prompt, ai.classify, ai.summarize, and ai.agent steps reference a model by ID in the step. Configure a Generative AI connector in Kibana and pass its ID in connector-id. For ai.agent, you can instead pass an inference endpoint ID in inference-id.

If you omit both, ai.agent uses the same model that Elastic Agent Builder would use for the agent. Refer to Model configuration in Elastic Agent Builder.

If you omit connector-id from ai.prompt, ai.classify, or ai.summarize:

Use the optional reasoning-level field on ai.prompt and ai.agent steps to control how much reasoning the model does before it responds. The field accepts none, minimal, low, medium, high, or xhigh, in lowercase. Only ai.prompt and ai.agent accept this field. How each level affects the response depends on the model and provider.

Whether the model receives the level depends on how the step connects to it:

• Elastic Managed LLMs and inference endpoints receive the level you set. If the model doesn't support that level, the step fails. Check the model provider's documentation for the levels each model supports.
• Other connectors, such as OpenAI, Amazon Bedrock, and Google Gemini, ignore the field, and the step runs normally.

On ai.agent steps:

• If you omit reasoning-level, the step uses the agent's default level. Only built-in agents have a default. For custom agents, or when the agent has no default, the model uses its own default.
• The level applies only to the agent's own model calls. It doesn't apply to the subagents that the agent starts, or to tasks that Elastic Agent Builder sends to the fast model.

For example, this step sets a high reasoning level for a custom agent:

- name: investigate
  type: ai.agent
  agent-id: "security-analyst-agent"
  reasoning-level: "high"
  with:
    message: "Investigate alert {{ event.alerts[0]._id }} and propose next steps."

• ai.prompt: Send a prompt to a model and receive a response. Supports structured output with a JSON Schema. Stack GA 9.4+ … The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Preview in 9.3 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
• ai.classify: Classify input into a fixed set of categories. Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
• ai.summarize: Generate a summary of the provided content. Stack 9.4+ The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
• ai.agent: Invoke an Elastic Agent Builder agent as a workflow step. Stack GA 9.4+ … The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Generally available since 9.4 This functionality is generally available and ready for production usage. Preview in 9.3 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.
• ai.conversation.create: Create an empty Elastic Agent Builder conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.conversation.add_event: Add an event, such as a note, to a conversation without triggering an agent response. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.conversation.add_user_message: Add a user message to a conversation without triggering an agent response. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.conversation.metadata.read: Read the metadata of a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.conversation.metadata.patch: Update the metadata of a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.attachment.add: Add an attachment to a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.attachment.update: Update an attachment in a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.attachment.delete: Delete an attachment from a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.attachment.read: Read the content of an attachment. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.
• ai.attachment.list: List the attachments in a conversation. Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Generally available This functionality is generally available and ready for production usage. Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

Where a step's fields go, and how they're named, depends on the step:

Whether you can use Liquid expressions in these top-level fields depends on your version:

Stack Planned The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Planned We plan to add this functionality in a future Elastic Stack update. Subject to changes. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes. Serverless Preview Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud. Availability Preview This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Serverless interfaces and procedures might differ from classic Elastic Stack deployments. ai.prompt and ai.agent also accept a top-level reasoning-level field. Refer to Reasoning level.

Schema convention. In each schema table on this page, the Location column indicates where each parameter sits in the YAML:

• top level: Alongside type and name, at the top of the step or trigger definition.
• `with`: Inside the step's with: block.
• `on`: Inside the trigger's on: block.

Call an LLM with a prompt. Supports optional structured output through a JSON Schema.

Output shape:

• Free text: { content: string, metadata: object }
• With schema: { content: <structured object matching schema>, metadata: object }

- name: summarize
  type: ai.prompt
  connector-id: "my-openai"
  with:
    prompt: |
      Summarize this alert in one sentence:
      {{ event.alerts[0] | json }}

- name: extract_details
  type: ai.prompt
  connector-id: "my-openai"
  with:
    prompt: "Extract key details from this alert: {{ event.alerts[0] | json }}"
    schema:
      type: "object"
      properties:
        severity:
          type: "string"
          enum: ["low", "medium", "high", "critical"]
        summary:
          type: "string"
        key_indicators:
          type: "array"
          items:
            type: "string"

The structured result is available at steps.extract_details.output.content.severity, and so on.

Classify input into one of a fixed set of categories. Optionally includes a rationale and supports multi-label classification.

Output shape:

- name: classify
  type: ai.classify
  connector-id: "my-bedrock"
  with:
    input: "${{ event.alerts[0] }}"
    categories: ["true_positive", "false_positive", "needs_investigation"]
    includeRationale: true
    fallbackCategory: "needs_investigation"

categories and fallbackCategory also accept an object with name and description instead of a plain string. When you supply a description, the step includes it in the classification prompt sent to the model, which improves category selection when categories are closely related or ambiguous. This doesn't affect category names in the output: category and categories in the step output always contain the category name, never the description.

- name: classify_alert
  type: ai.classify
  connector-id: "my-bedrock"
  with:
    input: "{{ inputs.alert_narrative }}"
    categories:
      - name: "Phishing"
        description: "User-targeted deception to steal credentials or deliver malicious links; no sustained host compromise pattern required."
      - name: "Malware"
        description: "Execution of malicious code, ransomware, or clear C2/beaconing on an endpoint."
      - name: "Credential Access"
        description: "Brute force, password spraying, or secret dumping without confirmed large outbound data transfer."
    fallbackCategory:
      name: "Unknown"
      description: "Insufficient signal to map confidently to any defined category."
    includeRationale: true

You can mix plain strings and objects in the same categories list: the classifier treats a plain string as a category with no description.

Summarize content with an LLM. Input can be a string, an array, or an object.

Output shape: { content: string, metadata?: object }.

- name: summary
  type: ai.summarize
  connector-id: "my-gemini"
  with:
    input: "${{ steps.gather.output }}"
    instructions: "Describe the root cause in two or three sentences."
    maxLength: 500

Invoke an Elastic Agent Builder agent as a workflow step. Useful when you want a multi-turn agent loop embedded inside a workflow. The agent handles tool selection, reasoning, and response synthesis. The workflow handles pre- and post-processing.

Output shape:

- name: investigate
  type: ai.agent
  agent-id: "security-analyst-agent"
  inference-id: "my-inference-endpoint"
  create-conversation: true
  with:
    message: |
      Investigate alert {{ event.alerts[0]._id }} and propose next steps.
    schema:
      type: "object"
      properties:
        findings:
          type: "array"
          items:
            type: "string"
        recommended_action:
          type: "string"

- name: followup
  type: ai.agent
  agent-id: "security-analyst-agent"
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    message: "Apply the recommended action and report back."

The following step summarizes the investigate conversation without changing it. The summary is in steps.summarize.output.message.

- name: summarize
  type: ai.agent
  agent-id: "security-analyst-agent"
  ephemeral: true
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    message: "Summarize this conversation in five bullet points."

Create an empty Elastic Agent Builder conversation without sending a message. Use the returned conversation_id in later steps, such as ai.conversation.add_event, ai.conversation.add_user_message, or ai.agent.

All parameters go in the with block and use snake_case.

Output shape:

If you set agent_id, set the same agent in agent-id on any ai.agent step that continues the conversation. Otherwise, ai.agent runs the default Elastic AI Agent, not the agent you set when you created the conversation.

- name: create_conversation
  type: ai.conversation.create
  with:
    title: "Checkout incident"

Add an event to an Elastic Agent Builder conversation without triggering an agent response. Kibana features can define their own event types, and each type defines the shape of its data payload. Elastic Agent Builder provides the text_note type for notes. The agent reads a note the next time it runs on the conversation. Other event types might only be shown in the conversation and not sent to the agent. The step works the same way as the add events to a conversation API.

All parameters go in the with block and use snake_case.

Output shape:

If the event type is unknown or data doesn't match the type, the step fails and adds nothing. You can't update or remove an event after you add it.

- name: create_conversation
  type: ai.conversation.create
  with:
    title: "Checkout incident"

- name: add_update
  type: ai.conversation.add_event
  with:
    conversation_id: "{{ steps.create_conversation.output.conversation_id }}"
    type: text_note
    data:
      title: "Status update"
      text: "Checkout service latency is back to normal."

- name: summarize
  type: ai.agent
  with:
    conversation_id: "{{ steps.create_conversation.output.conversation_id }}"
    message: "Summarize the status updates in this conversation."

Add a user message to an existing Elastic Agent Builder conversation without triggering an agent response. The agent reads the message the next time it runs on the conversation.

All parameters go in the with block and use snake_case.

Output shape: { conversation_id: string }.

Unlike ai.agent, this step doesn't accept attachments.

The following example runs in a workflow with an alert trigger, after an ai.conversation.create step named create_conversation. It adds the ID of the alert that triggered the workflow to the conversation:

- name: add_alert
  type: ai.conversation.add_user_message
  with:
    conversation_id: "{{ steps.create_conversation.output.conversation_id }}"
    message: "A new alert fired: {{ event.alerts[0]._id }}"

Conversation metadata is a set of structured fields, such as status or severity, that track the state of a conversation. The template applied to the conversation defines which fields exist and which values each one accepts.

Use these steps to read the metadata, for example to branch a workflow on a field's value, or to update it, for example to record the outcome of an investigation. The agent also sees the fields and their current values each time it runs on the conversation. In the chat, users see the template name as the conversation's type, but not the field values.

Only conversations with a template have metadata:

• Conversations that ai.agent creates, or that users start in chat, have no template.
• To create a conversation with a template from a workflow, use ai.conversation.create with template_id set to a built-in template: investigation or escalation. ai.conversation.create is in technical preview, so a workflow that creates a conversation with metadata depends on a preview step.

Both built-in templates, investigation and escalation, define the following fields:

The escalation template also has a linked_investigations field, a list of investigation IDs.

Read all metadata fields of a conversation.

Output shape: { metadata: object }. The current metadata fields and their values. Empty if the conversation has no metadata.

The following example runs in a separate workflow that receives the ID of an investigation conversation as an input, for example when another workflow calls it. It logs a message if the investigation is closed:

inputs:
  - name: conversation_id
    type: string
    required: true

steps:
  - name: read_metadata
    type: ai.conversation.metadata.read
    with:
      conversation_id: "{{ inputs.conversation_id }}"

  - name: check_status
    type: if
    condition: 'steps.read_metadata.output.metadata.status : "closed"'
    steps:
      - name: log_closed
        type: console
        with:
          message: "The investigation is closed."

Update one or more metadata fields of a conversation. The step merges your values into the existing metadata. Fields you don't include keep their current values.

The step has the following requirements:

• The conversation must have a template applied.
• You can only set fields that the template defines.
• Each value must match the field's type and constraints. For example, a field with a fixed list of values rejects any value that isn't in the list.
• You can't set a field to null or remove it. To clear a text or list field that isn't required, set it to an empty string or an empty list. You can't clear a required field, such as status, or a field with a fixed list of values.

The updates object has the following limits:

• 1 to 100 key-value pairs.
• Keys up to 256 characters.
• Values can be a string (up to 10,000 characters), a number, a boolean, or an array of up to 100 strings (up to 2,000 characters each).

Output shape:

The following example runs after an ai.conversation.create step named create_conversation that sets template_id: investigation. It closes the investigation and records why:

- name: resolve_investigation
  type: ai.conversation.metadata.patch
  with:
    conversation_id: "{{ steps.create_conversation.output.conversation_id }}"
    updates:
      status: "closed"
      close_reason: "resolved"
      severity: "low"

An attachment is content, such as a runbook or a dashboard, that you add to an Elastic Agent Builder conversation so the agent can use it as context. Each attachment has a type, such as text, that determines the shape of its content. When you update an attachment, the earlier content is kept as a previous version.

Use these steps to add, update, delete, read, and list the attachments in a conversation.

All parameters go in the with block and use snake_case. Every attachment step takes the conversation_id of the conversation the attachment belongs to.

The examples in this section use the conversation created by the investigate step in Example: Call an agent.

These steps follow the same access rules as the conversation metadata steps: the user who authorizes the run must be able to access both the conversation and the agent it uses.

Add an attachment to a conversation. Provide the content directly in data, or set origin to copy it from a Kibana object, such as a dashboard.

If you set origin without data, the step copies the object's content once, when it creates the attachment. Later changes to the object don't update the attachment. If you set both data and origin, the step uses data as the content and doesn't copy anything from the object. Not all attachment types support origin. For example, text doesn't, but the dashboard type, platform.dashboard.dashboard_state, does. To attach a dashboard, set type to platform.dashboard.dashboard_state and origin to the dashboard ID.

Output shape:

The following example adds a runbook to the conversation and shows it to users as soon as they open the conversation:

- name: add_runbook
  type: ai.attachment.add
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    type: text
    data:
      content: "Runbook: reset the checkout cache before retrying."
    description: "Checkout runbook"
    render_inline: true

Update the content or description of an attachment. You can't update a deleted attachment.

The step creates a new version only when data differs from the current content. Updating only description doesn't create a new version.

Output shape: { attachment_id: string, current_version: number }. current_version is the new version number when the content changed, and the existing version number otherwise.

The following example replaces the runbook's content, which creates version 2 of the attachment:

- name: update_runbook
  type: ai.attachment.update
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    attachment_id: "{{ steps.add_runbook.output.attachment_id }}"
    data:
      content: "Runbook: reset the checkout cache, then restart the payment service."

Delete an attachment from a conversation. By default, the step does a regular deletion: the attachment is marked as deleted, but its content and version history are kept. A deleted attachment no longer appears in the agent's list of attachments, and users no longer see it in the conversation. You can still read it with ai.attachment.read, and list it with include_deleted: true in ai.attachment.list. To remove the attachment and its history completely, set permanent: true.

You can't permanently delete an attachment in the following cases. Use a regular deletion instead.

• The agent has already used the attachment in the conversation, by reading it, updating it, or comparing its versions.
• The attachment, or its data, has a client_id field. This isn't the id you can set with ai.attachment.add.

Output shape: { success: boolean, permanent: boolean }.

The following example deletes the runbook. Because permanent isn't set, you can still read and list the attachment afterward:

- name: delete_runbook
  type: ai.attachment.delete
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    attachment_id: "{{ steps.add_runbook.output.attachment_id }}"

Read the content of an attachment. By default, the step returns the current version. You can also read an attachment that was deleted without permanent: true.

Output shape: { data: any, version: number }.

The following example reads version 1 of the runbook, which is its content from before the update:

- name: read_runbook
  type: ai.attachment.read
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"
    attachment_id: "{{ steps.add_runbook.output.attachment_id }}"
    version: 1

List the attachments of a conversation. The step returns a summary of each attachment, not its content. To get the content, use ai.attachment.read.

Output shape:

The following example lists the attachments in the conversation that haven't been deleted:

- name: list_attachments
  type: ai.attachment.list
  with:
    conversation_id: "{{ steps.investigate.output.conversation_id }}"

• Configured AI connectors: Set up the Generative AI connector referenced by connector-id.
• Switch step: A common pairing: classify with ai.classify, then dispatch with switch.
• Human-in-the-loop: Pair AI classifications with a reviewer gate for uncertain cases.
• Elastic Agent Builder overview: Concepts behind the agents referenced by ai.agent.
• Add events to a conversation with the API: Add the same events from outside a workflow.