Use Context Engine with Elastic Agent Builder

Use Context Engine with Elastic Agent Builder to give an agent access to context distilled from your organization's data. By retrieving relevant Knowledge Indicators (KIs) from an AI index instead of repeatedly discovering and interpreting source data, the agent can complete tasks faster and use fewer model tokens.

Assigning an AI index to an Elastic Agent Builder agent automatically makes the Context Engine retrieval skill available, which provides the retrieval tools and instructions. A retrieved KI can answer a question directly or guide the agent to current details in the source data. If the AI index has memory enabled, the agent can also save useful task context and retrieve it in later conversations.

For guidance that applies to every agent integration, refer to Configure agents to use an AI index. For the list, describe, and query flow, refer to Retrieve context from an AI index.

You need:

• Context Engine enabled in the current Kibana space.
• An AI index that contains at least one KI. To create one, follow the Context Engine quickstart.
• 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 Context Engine is enabled and an agent has at least one assigned AI index, Elastic Agent Builder automatically makes the hidden ki-retrieval skill available to that agent, regardless of its type. The skill does not appear in the skill library or agent skill picker. When the agent loads the skill, it receives three dedicated Context Engine retrieval 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.

If an assigned AI index has memory enabled, Elastic Agent Builder also gives the agent platform.context_engine.remember and platform.context_engine.forget. These tools let it save useful task context and exclude obsolete memories from later retrieval. To configure and test memory, refer to Save and retrieve memories with Context Engine.

Elastic Agent Builder lists the available AI indices in the agent's system instructions and directs the agent to load the skill for retrieval guidance. You do not need to add the skill or 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.