AI steps

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

AI steps can also create Elastic Agent Builder conversations and add content to them without triggering an agent response.

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:

• ai.prompt: Send a prompt to a model and receive a response. Supports structured output with a JSON Schema.
• ai.classify: Classify input into a fixed set of categories.
• ai.summarize: Generate a summary of the provided content.
• ai.agent: Invoke an Elastic Agent Builder agent as a workflow step.
• ai.conversation.create: Create an empty Elastic Agent Builder conversation.
• ai.conversation.add_event: Add an event, such as a note, to a conversation without triggering an agent response.
• ai.conversation.add_user_message: Add a user message to a conversation without triggering an agent response.

For ai.prompt, ai.classify, ai.summarize, and ai.agent, connector-id, agent-id, and inference-id are top-level step fields (alongside name, type, if, foreach) and are written in kebab-case. They are not nested under with, and not connectorId. Inside with, most of their parameters use camelCase (systemPrompt, maxLength, includeRationale). The conversation steps have no top-level fields and use snake_case inside with.

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.

The step ignores public-conversation if create-conversation isn't true, or if it continues an existing conversation instead of creating one. Neither case returns an error.

Output shape:

- name: investigate
  type: ai.agent
  agent-id: "security-analyst-agent"
  connector-id: "my-openai"
  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."
		

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 }}"
		

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