Use Context Engine with Elastic Agent Builder

When you assign an AI index to an Elastic Agent Builder agent, the agent can retrieve Knowledge Indicators (KIs) during a conversation. It can answer from a KI or use the KI's guidance to query source data when the question requires current details.

You need:

• Context Engine enabled in the current Kibana space.
• An AI index that contains at least one KI. To create one, follow Get started with Context Engine.
• Access to create or edit an Elastic Agent Builder agent and read the AI index.
• Access to the underlying data and an appropriate agent tool if the agent must query source data.

You can assign an AI index while creating a custom agent or by editing an existing agent:

1. In Elastic Agent Builder, open Manage components, then select Agents.
2. Create an agent, or open an agent that you can edit.
3. For an existing agent, select Edit agent settings. For a new agent, remain on the Settings tab.
4. In AI Indices, select the AI index under Additional indices.
5. Save the agent.

The list contains AI indices registered in the current space that you can access. Some agent types also include default AI indices supplied by Elastic. Default AI indices apply automatically and cannot be removed from the agent.

When an agent has at least one AI index, Elastic Agent Builder automatically gives it three dedicated Context Engine tools:

• list_ai_indices lists the accessible AI indices and their query targets.
• describe_ai_index returns the selected AI index's purpose, fields, KI types, tags, and example queries.
• query_ai_indices runs an ES|QL query against AI indices with the current space applied automatically.

Elastic Agent Builder also adds the available AI indices and retrieval guidance to the agent's system instructions. You do not need to add the three tools manually or repeat their sequence in custom instructions.

The assignment provides access to KIs, not to the original source data. If a KI contains an ES|QL pattern for retrieving current details, the agent also needs a source-query tool such as platform.core.execute_esql and permission to read the source indices. For a custom agent, you can enable built-in Elastic capabilities or assign only the source tools required for its task.

Use Custom instructions to define the agent's scope and the behavior that is specific to your use case. For example:

Use the <AI index ID> AI index for questions about <subject>.
Answer from a retrieved Knowledge Indicator when it contains enough information.
For current values or detailed records, use the KI's query guidance to query the source data.
State when the available data cannot answer the question.
		

Start with concise instructions. Add more detail only when testing reveals a specific behavior that the AI index metadata, KI content, and tool descriptions do not already handle. For general guidance, refer to Prompt engineering.

Open a conversation with the agent and test the context it can use:

1. Ask a question that a KI should answer directly, such as what a dataset represents or which questions it cannot answer.
2. Confirm that the agent selects the expected AI index and retrieves a relevant KI.
3. If the agent has a source-query tool, ask for a current value or detailed record that requires the KI's query guidance.
4. Confirm that the agent queries the source instead of presenting a stored summary as current data.
5. Ask an out-of-scope question and confirm that the agent does not force an answer from an unrelated KI.

To inspect a conversation round in detail, select View Trace and review its model and tool calls. Refer to View traces for a conversation round for trace availability and privacy settings.

Use the observed behavior to decide what to change:

For a structured review process, refer to Evaluate and improve Knowledge Indicators.