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.
• Experimental features enabled in Elastic Agent Builder. The Context Engine retrieval tools are not attached to an agent unless both settings are on.
• 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:

• platform.context_engine.list_ai_indices lists the accessible AI indices and their query targets.
• platform.context_engine.describe_ai_index returns the selected AI index's purpose, fields, KI types, tags, and example queries.
• platform.context_engine.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.

Custom instructions are optional. Elastic Agent Builder already adds AI index metadata and retrieval guidance to the agent's system instructions. Advanced users can add Custom instructions for requirements that apply to every conversation with the agent and are not covered by the AI index metadata, KI content, or tool descriptions.

Keep the instructions focused on the agent's task, audience, priorities, and boundaries. For example:

Answer questions for <audience> about <subject>.
Prioritize <goals or criteria> when making recommendations.
Do not provide guidance about <out-of-scope area>.
When the available information is incomplete, state the limitation and ask for <required input>.
		

Do not repeat the AI index retrieval sequence or prescribe how the agent should choose between KIs and source data. Add more detail only when testing reveals a specific unmet requirement. 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.