Call Elastic Agent Builder agents from Elastic Workflows

Elastic Workflows and Elastic Agent Builder allow you to combine deterministic automation with conversational reasoning. By invoking an AI agent directly within a workflow execution, you can treat the agent as a "reasoning engine" that summarizes data, classifies events, or makes decisions before passing the results to the next step in your automation.

There are two ways to integrate agents into your workflows:

• The ai.agent step: A simplified shorthand step for common operations. Use this when you want to send a prompt to an agent and receive a text response without complex configuration.
• The kibana.request step: A generic step that provides full access to the Elastic Agent Builder APIs. Use this for advanced use cases, such as listing available agents or managing agent sessions programmatically.

Before you begin:

• Familiarize yourself with the core concepts of Elastic Workflows.
• Enable the Workflows feature in Advanced settings.
• Ensure you have the correct privileges to create and run workflows.
• For details, refer to Set up workflows.
• Create at least one workflow.

Follow these steps to invoke an ai.agent as a step within a workflow.

1. Open the Workflows editor and create or edit a workflow.
2. Add a new step with the type ai.agent.
3. Set the agent-id parameter at the top level of the step to the unique identifier of the target agent. If you omit it, the step uses the built-in Elastic AI Agent.
4. In the with block, set the message parameter to your natural language prompt.
5. Optionally, in the with block, set the schema parameter to a JSON Schema object to receive structured output from the agent instead of free-text.
6. Optionally, route the step to a specific model by setting connector-id or inference-id at the top level of the step. These parameters are mutually exclusive.

The following example demonstrates a workflow that searches for flight delays and uses the Elastic AI Agent to summarize the impact. To follow along with this example ensure that the Kibana sample flight data is installed.

version: "1"
name: analyze_flight_delays
description: Fetches delayed flights and uses an agent to summarize the impact.
enabled: true
triggers:
  - type: manual
steps:
  # Step 1: Get data from Elasticsearch
  - name: get_delayed_flights
    type: elasticsearch.search
    with:
      index: "kibana_sample_data_flights"
      query:
        range:
          FlightDelayMin:
            gt: 60
      size: 5

  # Step 2: Ask the agent to reason over the data
  - name: summarize_delays
    type: ai.agent
    agent-id: "elastic-ai-agent"
    with:
      message: |
        Review the following flight delay records and summarize which airlines are most affected and the average delay time:
        {{ steps.get_delayed_flights.output }}

  # Step 3: Print the agent's summary
  - name: print_summary
    type: console
    with:
      message: "{{ steps.summarize_delays.output }}"
		

1. agent-id: The ID of the agent you want to call (must exist in Agent Builder). Set it at the top level of the step, not in the with block.
2. message: The prompt sent to the agent. You can use template variables (like {{ steps.step_name.output }}) to inject data dynamically.

Set agent-id and other configuration keys at the top level of the step. Set inputs like message in the with block.

For the complete step reference, refer to ai.agent.

Use the generic kibana.request step to interact with Elastic Agent Builder APIs programmatically.

1. Add a new step with the type kibana.request.
2. Set the method (for example: GET, POST).
3. Set the path to the specific Agent Builder API endpoint.

This step retrieves a list of all agents currently available in Agent Builder.

name: list_agents
enabled: true
triggers:
  - type: manual
steps:
  - name: list_agents
    type: kibana.request
    with:
      method: GET
      path: /api/agent_builder/agents
		

The elastic/workflows GitHub repo contains more than 50 examples you can use as a starting point.

• Tools overview
• Workflow tools
• Workflows
• Agent Builder API