Elastic Stack (ELK Stack) agent builder API
Agent Builder is a set of AI-powered capabilities for developing and interacting with agents that work with your Elasticsearch data. Most users will probably want to integrate with Agent Builder using MCP or A2A, but you can also work programmatically with tools, agents, and conversations using these Kibana APIs. Follow the [Agent Builder API tutorial](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/agent-builder-api-tutorial) for a guided example. **Elastic Agent Builder requires an Enterprise subscription.**
Operations 41
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Ask an LLM
“Can an external A2A client hand a task to one of my Agent Builder agents?”
“What endpoint does an A2A SDK post tasks to for an Elastic agent?”
Tell an agent
Send an A2A task to agent {agentId} over the agent-to-agent protocol.
Point my A2A client at agent {agentId} so it can submit tasks.
Ask an LLM
“Where do I find the A2A agent card that advertises an Agent Builder agent for discovery?”
“What metadata does the A2A agent card JSON expose about my agent?”
Tell an agent
Fetch the A2A agent card JSON for agent {agentId}.
Show the discovery metadata other A2A clients see for agent {agentId}.
Ask an LLM
“Which agents are defined in my Kibana Agent Builder?”
“Can I see every agent along with the tools assigned to it?”
Tell an agent
List all my Agent Builder agents with their configuration.
Show every available agent and the tools each one has.
Ask an LLM
“How do I create a new custom agent in Elastic Agent Builder?”
“What do I need to supply to define a new agent's behavior and tools?”
Tell an agent
Create a new agent with id {id} named {name}, described as {description}.
Define agent {name} using configuration {configuration} and labels {labels}.
POST
/api/agent_builder/agents/{agent_id}/consumption
Get an agent's token consumption per conversation · Get agent consumption data
#
Ask an LLM
“How many LLM tokens has a given agent used in each conversation?”
“Can I find the conversations where an agent triggered high token usage warnings?”
Tell an agent
Show per-conversation token consumption for agent {agent_id}.
List only conversations flagged with token usage warnings for agent {agent_id}.
Ask an LLM
“Is deleting an Agent Builder agent permanent?”
“How do I remove an agent I no longer need?”
Tell an agent destructive · confirm first
Delete agent {id} permanently.
Remove the Agent Builder agent {id}.
Ask an LLM
“What configuration and tool assignments does a specific agent have?”
“Can I look up a single Agent Builder agent by its id?”
Tell an agent
Get the full definition of agent {id}.
Show the configuration and tools assigned to agent {id}.
Ask an LLM
“Can I change the instructions or tools of an agent I already created?”
“How do I rename an existing Agent Builder agent or change its avatar?”
Tell an agent
Update agent {id} with new configuration {configuration}.
Rename existing agent {id} to {name}.
GET
/api/agent_builder/agents/{id}/access_control
View who can access an agent · Get an agent's access control list
#
Ask an LLM
“Who has access to a particular agent and at what permission level?”
“Can I check whether I'm allowed to manage an agent's access control list?”
Tell an agent
Show the access control list for agent {id}.
List the users and roles granted access to agent {id}.
PUT
/api/agent_builder/agents/{id}/access_control
Replace an agent's access control entries · Update an agent's access control list
#
Ask an LLM
“How do I share an agent with other users or give someone Manager rights on it?”
“Does updating an agent's access list replace all existing entries?”
Tell an agent
Replace the access control entries on agent {id} with {entries}.
Grant these users access to agent {id}: {entries}.
Ask an LLM
“Where can I see all my past agent chat conversations?”
“Can I filter my conversation history to just one agent?”
Tell an agent
List all my agent conversations.
Show only the conversations I've had with agent {agent_id}.
Ask an LLM
“Can I get a conversation ID before sending the first chat message?”
“How do I open a blank conversation with an agent without sending anything yet?”
Tell an agent
Create an empty conversation with agent {agent_id} titled {title}.
Open a new blank conversation and give me its ID.
DELETE
/api/agent_builder/conversations/{conversation_id}
Delete a conversation · Delete conversation by ID
#
Ask an LLM
“Can I permanently delete an agent conversation?”
“Is there a way to undo deleting a chat conversation?”
Tell an agent destructive · confirm first
Delete conversation {conversation_id}.
Permanently remove the chat conversation {conversation_id}.
GET
/api/agent_builder/conversations/{conversation_id}
Get a conversation's full history · Get conversation by ID
#
Ask an LLM
“How can I read back every message in one agent conversation?”
“What metadata is stored with a single conversation?”
Tell an agent
Get the full message history of conversation {conversation_id}.
Show conversation {conversation_id} with all its messages.
PUT
/api/agent_builder/conversations/{conversation_id}/access_control
Set who can see a conversation · Update a conversation's access control
#
Ask an LLM
“How do I share one of my agent conversations with teammates?”
“Who is allowed to change a conversation's access mode?”
Tell an agent
Set conversation {conversation_id} to access mode {access_mode} with members {entries}.
Make conversation {conversation_id} {access_mode} and remove all shared members.
GET
/api/agent_builder/conversations/{conversation_id}/attachments
List a conversation's attachments · List conversation attachments
#
Ask an LLM
“What files or data are attached to an agent conversation?”
“Can I also see attachments that were soft-deleted from a conversation?”
Tell an agent
List the attachments in conversation {conversation_id}.
List all attachments in conversation {conversation_id}, including soft-deleted ones.
POST
/api/agent_builder/conversations/{conversation_id}/attachments
Attach data to a conversation · Create conversation attachment
#
Ask an LLM
“How do I add an attachment to an existing agent conversation?”
“Are conversation attachments versioned when I add them?”
Tell an agent
Attach {data} as a {type} attachment to conversation {conversation_id}.
Add a hidden {type} attachment with {data} to conversation {conversation_id}.
DELETE
/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}
Delete a conversation attachment · Delete conversation attachment
#
Ask an LLM
“Is removing a conversation attachment a soft delete I can undo?”
“How do I permanently purge an attachment nothing references anymore?”
Tell an agent destructive · confirm first
Delete attachment {attachment_id} from conversation {conversation_id}.
Permanently purge unreferenced attachment {attachment_id} from conversation {conversation_id}.
PATCH
/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}
Rename a conversation attachment · Rename attachment
#
Ask an LLM
“Can I rename an attachment without creating a new version of it?”
“Is there a way to change only an attachment's description label?”
Tell an agent
Rename attachment {attachment_id} in conversation {conversation_id} to {description}.
Relabel attachment {attachment_id} in conversation {conversation_id} as {description} without versioning it.
PUT
/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}
Replace an attachment's content · Update conversation attachment
#
Ask an LLM
“Does changing an attachment's content create a new version?”
“Can I edit the data inside an attachment already in a conversation?”
Tell an agent
Update the content of attachment {attachment_id} in conversation {conversation_id} to {data}.
Save a new version of attachment {attachment_id} in conversation {conversation_id} with {data}.
POST
/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/_restore
Restore a soft-deleted attachment · Restore deleted attachment
#
Ask an LLM
“Can I bring back an attachment I deleted from a conversation?”
“How do I undo a soft delete on a conversation attachment?”
Tell an agent
Restore deleted attachment {attachment_id} in conversation {conversation_id}.
Undelete attachment {attachment_id} from conversation {conversation_id}.
PUT
/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/origin
Link an attachment to its saved origin · Update attachment origin
#
Ask an LLM
“After saving a by-value attachment, how do I link it to its persistent store?”
“Can I change the origin reference an attachment points to?”
Tell an agent
Set the origin of attachment {attachment_id} in conversation {conversation_id} to {origin}.
Link attachment {attachment_id} in conversation {conversation_id} to its saved source {origin}.
GET
/api/agent_builder/conversations/{conversation_id}/attachments/stale
Check if conversation attachments are stale · Check attachment staleness
#
Ask an LLM
“Have any attachments in my conversation drifted from their original source?”
“Which conversation attachments are out of date compared with their origin snapshot?”
Tell an agent
Check which attachments in conversation {conversation_id} are stale.
Compare attachments in conversation {conversation_id} against their origin snapshots.
Ask an LLM
“How do I send a message to an Elastic agent and get back its complete reply in one response?”
“Can I continue an existing conversation by passing its ID with my next message?”
Tell an agent
Ask agent {agent_id}: {input} and wait for the full answer.
Send {input} in conversation {conversation_id} and return the final response.
POST
/api/agent_builder/converse/async
Chat with an agent and stream events · Send chat message (streaming)
#
Ask an LLM
“Can I watch an agent's intermediate reasoning steps stream in as it works?”
“Is there a streaming version of agent chat that sends real-time events?”
Tell an agent
Stream agent {agent_id}'s reply to {input} as live events.
Send {input} to conversation {conversation_id} and stream the steps as they happen.
Ask an LLM
“Can I use Agent Builder tools from an MCP client like an IDE assistant?”
“What is the MCP server endpoint Kibana exposes for Agent Builder?”
Tell an agent
Connect my MCP client to the Agent Builder MCP server.
Expose Agent Builder tools in namespace {namespace} over MCP.
Ask an LLM
“Which plugins are installed in Agent Builder and what assets do they manage?”
“What skills have come in through installed plugins?”
Tell an agent
List all installed Agent Builder plugins.
Show every plugin and the managed assets it bundles.
Ask an LLM
“How do I uninstall a plugin from Agent Builder?”
“Can I force-remove a plugin even if its assets are still in use?”
Tell an agent destructive · confirm first
Uninstall plugin {pluginId}.
Force delete plugin {pluginId}.
Ask an LLM
“What does a specific installed plugin contain?”
“Can I look up one Agent Builder plugin by id?”
Tell an agent
Get the details of plugin {pluginId}.
Show what plugin {pluginId} installed.
Ask an LLM
“Can I install an agent plugin straight from a GitHub URL or a ZIP file?”
“What formats does Agent Builder accept when installing a plugin?”
Tell an agent
Install the plugin from {url}.
Install the plugin at {url} under the name {plugin_name}.
Ask an LLM
“What skills are available to my agents, built-in and custom?”
“Can I include skills that came from installed plugins in the list?”
Tell an agent
List all Agent Builder skills.
List skills including those provided by plugins.
Ask an LLM
“How do I write my own skill for Agent Builder agents?”
“Can a new skill reference specific tools?”
Tell an agent
Create skill {id} named {name}, described as {description}, with content {content}.
Add a skill {name} whose content is {content} and that uses tools {tool_ids}.
Ask an LLM
“What happens if I delete a skill that agents still reference?”
“Can built-in skills be deleted?”
Tell an agent destructive · confirm first
Delete skill {skillId}.
Force delete skill {skillId} and detach it from any agents.
Ask an LLM
“What content and tools does a particular skill define?”
“Can I fetch one skill by its id?”
Tell an agent
Get skill {skillId}.
Show the content of skill {skillId}.
Ask an LLM
“Can I edit a skill I created earlier?”
“Is it possible to change the tools a user-created skill uses?”
Tell an agent
Update skill {skillId} with new content {content}.
Change the tools used by skill {skillId} to {tool_ids}.
Ask an LLM
“Which tools can my Agent Builder agents call?”
“Can I see each tool's schema and configuration requirements?”
Tell an agent
List all Agent Builder tools.
Show every available tool with its schema.
Ask an LLM
“How do I define a custom tool for my agents to use?”
“Can I require confirmation before an agent runs a tool I create?”
Tell an agent
Create a {type} tool with id {tool_id} and configuration {configuration}.
Create tool {tool_id} of type {type}, tagged {tags}, with configuration {configuration}.
Ask an LLM
“Can I test a tool by running it directly with my own inputs, outside a chat?”
“Is it possible to run a tool through a specific connector?”
Tell an agent
Run tool {tool_id} with parameters {tool_params}.
Execute tool {tool_id} with {tool_params} using connector {connector_id}.
Ask an LLM
“Is deleting a tool from Agent Builder reversible?”
“Can I force the removal of a tool agents are still using?”
Tell an agent destructive · confirm first
Delete tool {toolId}.
Force delete tool {toolId} even if agents use it.
Ask an LLM
“What parameters and configuration does one particular tool expect?”
“Can I retrieve a single tool definition by id?”
Tell an agent
Get the definition of tool {toolId}.
Show the schema for tool {toolId}.
Ask an LLM
“Can I change the configuration of a tool that already exists?”
“How do I retag or redescribe an existing tool?”
Tell an agent
Update tool {toolId} with configuration {configuration}.
Set the tags on tool {toolId} to {tags}.