Elastic Stack · OpenAPI Overlay 1.0.0
API Evangelist conversational phrasing for Kibana agent builder API
42 actions
42 updates
phrasing
extends
openapi/elk-stack-agent-builder-api-openapi.yml
Generated by API Evangelist
Written by API Evangelist tooling for Elastic Stack's API. It is a proposal applied on top of the contract, not a document Elastic Stack publishes.
What the actions change
x-apievangelist-phrasing
Targets 42 · first 16 shown; the file carries all of them
$.info
$.paths['/api/agent_builder/a2a/{agentId}'].post
$.paths['/api/agent_builder/a2a/{agentId}.json'].get
$.paths['/api/agent_builder/agents'].get
$.paths['/api/agent_builder/agents'].post
$.paths['/api/agent_builder/agents/{agent_id}/consumption'].post
$.paths['/api/agent_builder/agents/{id}'].get
$.paths['/api/agent_builder/agents/{id}'].put
$.paths['/api/agent_builder/agents/{id}'].delete
$.paths['/api/agent_builder/agents/{id}/access_control'].get
$.paths['/api/agent_builder/agents/{id}/access_control'].put
$.paths['/api/agent_builder/conversations'].get
$.paths['/api/agent_builder/conversations'].post
$.paths['/api/agent_builder/conversations/{conversation_id}'].get
$.paths['/api/agent_builder/conversations/{conversation_id}'].delete
$.paths['/api/agent_builder/conversations/{conversation_id}/access_control'].put
OpenAPI Overlay
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
title: API Evangelist conversational phrasing for Kibana agent builder API
version: 1.0.0
extends: openapi/elk-stack-agent-builder-api-openapi.yml
actions:
- target: $.info
update:
x-apievangelist-phrasing:
method: generated
generated: '2026-09-26'
generator: build-phrasing.py
label: Generated by API Evangelist
operations: 41
- target: $.paths['/api/agent_builder/a2a/{agentId}'].post
update:
x-apievangelist-phrasing:
intent: Send an A2A protocol task to an agent
effect: write
questions:
- 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?
instructions:
- text: Send an A2A task to agent {agentId} over the agent-to-agent protocol.
slots:
agentId: path.agentId
- text: Point my A2A client at agent {agentId} so it can submit tasks.
slots:
agentId: path.agentId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/a2a/{agentId}.json'].get
update:
x-apievangelist-phrasing:
intent: Get an agent's A2A discovery card
effect: read
questions:
- 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?
instructions:
- text: Fetch the A2A agent card JSON for agent {agentId}.
slots:
agentId: path.agentId
- text: Show the discovery metadata other A2A clients see for agent {agentId}.
slots:
agentId: path.agentId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents'].get
update:
x-apievangelist-phrasing:
intent: List Agent Builder agents
effect: read
questions:
- Which agents are defined in my Kibana Agent Builder?
- Can I see every agent along with the tools assigned to it?
instructions:
- text: List all my Agent Builder agents with their configuration.
- text: Show every available agent and the tools each one has.
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents'].post
update:
x-apievangelist-phrasing:
intent: Create an Agent Builder agent
effect: write
questions:
- 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?
instructions:
- text: Create a new agent with id {id} named {name}, described as {description}.
slots:
id: requestBody.id
name: requestBody.name
description: requestBody.description
- text: Define agent {name} using configuration {configuration} and labels {labels}.
slots:
name: requestBody.name
configuration: requestBody.configuration
labels: requestBody.labels
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{agent_id}/consumption'].post
update:
x-apievangelist-phrasing:
intent: Get an agent's token consumption per conversation
effect: read
questions:
- 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?
- Which users are driving an agent's input and output token counts?
instructions:
- text: Show per-conversation token consumption for agent {agent_id}.
slots:
agent_id: path.agent_id
- text: List only conversations flagged with token usage warnings for agent {agent_id}.
slots:
agent_id: path.agent_id
- text: Break down agent {agent_id} token usage for users {usernames}.
slots:
agent_id: path.agent_id
usernames: requestBody.usernames
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].get
update:
x-apievangelist-phrasing:
intent: Get one agent's full definition
effect: read
questions:
- What configuration and tool assignments does a specific agent have?
- Can I look up a single Agent Builder agent by its id?
instructions:
- text: Get the full definition of agent {id}.
slots:
id: path.id
- text: Show the configuration and tools assigned to agent {id}.
slots:
id: path.id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].put
update:
x-apievangelist-phrasing:
intent: Update an existing agent
effect: write
questions:
- 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?
instructions:
- text: Update agent {id} with new configuration {configuration}.
slots:
id: path.id
configuration: requestBody.configuration
- text: Rename existing agent {id} to {name}.
slots:
id: path.id
name: requestBody.name
- text: Change the avatar color of agent {id} to {avatar_color}.
slots:
id: path.id
avatar_color: requestBody.avatar_color
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}'].delete
update:
x-apievangelist-phrasing:
intent: Delete an agent
effect: destructive
questions:
- Is deleting an Agent Builder agent permanent?
- How do I remove an agent I no longer need?
instructions:
- text: Delete agent {id} permanently.
slots:
id: path.id
- text: Remove the Agent Builder agent {id}.
slots:
id: path.id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}/access_control'].get
update:
x-apievangelist-phrasing:
intent: View who can access an agent
effect: read
questions:
- 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?
instructions:
- text: Show the access control list for agent {id}.
slots:
id: path.id
- text: List the users and roles granted access to agent {id}.
slots:
id: path.id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/agents/{id}/access_control'].put
update:
x-apievangelist-phrasing:
intent: Replace an agent's access control entries
effect: write
questions:
- 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?
instructions:
- text: Replace the access control entries on agent {id} with {entries}.
slots:
id: path.id
entries: requestBody.entries
- text: 'Grant these users access to agent {id}: {entries}.'
slots:
id: path.id
entries: requestBody.entries
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations'].get
update:
x-apievangelist-phrasing:
intent: List agent chat conversations
effect: read
questions:
- Where can I see all my past agent chat conversations?
- Can I filter my conversation history to just one agent?
instructions:
- text: List all my agent conversations.
- text: Show only the conversations I've had with agent {agent_id}.
slots:
agent_id: query.agent_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations'].post
update:
x-apievangelist-phrasing:
intent: Start an empty conversation
effect: write
questions:
- 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?
instructions:
- text: Create an empty conversation with agent {agent_id} titled {title}.
slots:
agent_id: requestBody.agent_id
title: requestBody.title
- text: Open a new blank conversation and give me its ID.
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}'].get
update:
x-apievangelist-phrasing:
intent: Get a conversation's full history
effect: read
questions:
- How can I read back every message in one agent conversation?
- What metadata is stored with a single conversation?
instructions:
- text: Get the full message history of conversation {conversation_id}.
slots:
conversation_id: path.conversation_id
- text: Show conversation {conversation_id} with all its messages.
slots:
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}'].delete
update:
x-apievangelist-phrasing:
intent: Delete a conversation
effect: destructive
questions:
- Can I permanently delete an agent conversation?
- Is there a way to undo deleting a chat conversation?
instructions:
- text: Delete conversation {conversation_id}.
slots:
conversation_id: path.conversation_id
- text: Permanently remove the chat conversation {conversation_id}.
slots:
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/access_control'].put
update:
x-apievangelist-phrasing:
intent: Set who can see a conversation
effect: write
questions:
- How do I share one of my agent conversations with teammates?
- Who is allowed to change a conversation's access mode?
instructions:
- text: Set conversation {conversation_id} to access mode {access_mode} with members {entries}.
slots:
conversation_id: path.conversation_id
access_mode: requestBody.access_mode
entries: requestBody.entries
- text: Make conversation {conversation_id} {access_mode} and remove all shared members.
slots:
conversation_id: path.conversation_id
access_mode: requestBody.access_mode
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments'].get
update:
x-apievangelist-phrasing:
intent: List a conversation's attachments
effect: read
questions:
- What files or data are attached to an agent conversation?
- Can I also see attachments that were soft-deleted from a conversation?
instructions:
- text: List the attachments in conversation {conversation_id}.
slots:
conversation_id: path.conversation_id
- text: List all attachments in conversation {conversation_id}, including soft-deleted ones.
slots:
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments'].post
update:
x-apievangelist-phrasing:
intent: Attach data to a conversation
effect: write
questions:
- How do I add an attachment to an existing agent conversation?
- Are conversation attachments versioned when I add them?
instructions:
- text: Attach {data} as a {type} attachment to conversation {conversation_id}.
slots:
data: requestBody.data
type: requestBody.type
conversation_id: path.conversation_id
- text: Add a hidden {type} attachment with {data} to conversation {conversation_id}.
slots:
type: requestBody.type
data: requestBody.data
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].put
update:
x-apievangelist-phrasing:
intent: Replace an attachment's content
effect: write
questions:
- Does changing an attachment's content create a new version?
- Can I edit the data inside an attachment already in a conversation?
instructions:
- text: Update the content of attachment {attachment_id} in conversation {conversation_id} to {data}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
data: requestBody.data
- text: Save a new version of attachment {attachment_id} in conversation {conversation_id} with {data}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
data: requestBody.data
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].delete
update:
x-apievangelist-phrasing:
intent: Delete a conversation attachment
effect: destructive
questions:
- Is removing a conversation attachment a soft delete I can undo?
- How do I permanently purge an attachment nothing references anymore?
instructions:
- text: Delete attachment {attachment_id} from conversation {conversation_id}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
- text: Permanently purge unreferenced attachment {attachment_id} from conversation {conversation_id}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}'].patch
update:
x-apievangelist-phrasing:
intent: Rename a conversation attachment
effect: write
questions:
- Can I rename an attachment without creating a new version of it?
- Is there a way to change only an attachment's description label?
instructions:
- text: Rename attachment {attachment_id} in conversation {conversation_id} to {description}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
description: requestBody.description
- text: Relabel attachment {attachment_id} in conversation {conversation_id} as {description} without versioning it.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
description: requestBody.description
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/_restore'].post
update:
x-apievangelist-phrasing:
intent: Restore a soft-deleted attachment
effect: write
questions:
- Can I bring back an attachment I deleted from a conversation?
- How do I undo a soft delete on a conversation attachment?
instructions:
- text: Restore deleted attachment {attachment_id} in conversation {conversation_id}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
- text: Undelete attachment {attachment_id} from conversation {conversation_id}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/{attachment_id}/origin'].put
update:
x-apievangelist-phrasing:
intent: Link an attachment to its saved origin
effect: write
questions:
- 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?
instructions:
- text: Set the origin of attachment {attachment_id} in conversation {conversation_id} to {origin}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
origin: requestBody.origin
- text: Link attachment {attachment_id} in conversation {conversation_id} to its saved source {origin}.
slots:
attachment_id: path.attachment_id
conversation_id: path.conversation_id
origin: requestBody.origin
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/conversations/{conversation_id}/attachments/stale'].get
update:
x-apievangelist-phrasing:
intent: Check if conversation attachments are stale
effect: read
questions:
- Have any attachments in my conversation drifted from their original source?
- Which conversation attachments are out of date compared with their origin snapshot?
instructions:
- text: Check which attachments in conversation {conversation_id} are stale.
slots:
conversation_id: path.conversation_id
- text: Compare attachments in conversation {conversation_id} against their origin snapshots.
slots:
conversation_id: path.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/converse'].post
update:
x-apievangelist-phrasing:
intent: Chat with an agent and wait for the answer
effect: write
questions:
- 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?
instructions:
- text: 'Ask agent {agent_id}: {input} and wait for the full answer.'
slots:
agent_id: requestBody.agent_id
input: requestBody.input
- text: Send {input} in conversation {conversation_id} and return the final response.
slots:
input: requestBody.input
conversation_id: requestBody.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/converse/async'].post
update:
x-apievangelist-phrasing:
intent: Chat with an agent and stream events
effect: write
questions:
- 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?
instructions:
- text: Stream agent {agent_id}'s reply to {input} as live events.
slots:
agent_id: requestBody.agent_id
input: requestBody.input
- text: Send {input} to conversation {conversation_id} and stream the steps as they happen.
slots:
input: requestBody.input
conversation_id: requestBody.conversation_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/mcp'].post
update:
x-apievangelist-phrasing:
intent: Connect an MCP client to Agent Builder tools
effect: write
questions:
- 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?
instructions:
- text: Connect my MCP client to the Agent Builder MCP server.
- text: Expose Agent Builder tools in namespace {namespace} over MCP.
slots:
namespace: query.namespace
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins'].get
update:
x-apievangelist-phrasing:
intent: List installed Agent Builder plugins
effect: read
questions:
- Which plugins are installed in Agent Builder and what assets do they manage?
- What skills have come in through installed plugins?
instructions:
- text: List all installed Agent Builder plugins.
- text: Show every plugin and the managed assets it bundles.
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/{pluginId}'].get
update:
x-apievangelist-phrasing:
intent: Get an installed plugin
effect: read
questions:
- What does a specific installed plugin contain?
- Can I look up one Agent Builder plugin by id?
instructions:
- text: Get the details of plugin {pluginId}.
slots:
pluginId: path.pluginId
- text: Show what plugin {pluginId} installed.
slots:
pluginId: path.pluginId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/{pluginId}'].delete
update:
x-apievangelist-phrasing:
intent: Uninstall a plugin
effect: destructive
questions:
- How do I uninstall a plugin from Agent Builder?
- Can I force-remove a plugin even if its assets are still in use?
instructions:
- text: Uninstall plugin {pluginId}.
slots:
pluginId: path.pluginId
- text: Force delete plugin {pluginId}.
slots:
pluginId: path.pluginId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/plugins/install'].post
update:
x-apievangelist-phrasing:
intent: Install a plugin from a URL
effect: write
questions:
- 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?
instructions:
- text: Install the plugin from {url}.
slots:
url: requestBody.url
- text: Install the plugin at {url} under the name {plugin_name}.
slots:
url: requestBody.url
plugin_name: requestBody.plugin_name
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills'].get
update:
x-apievangelist-phrasing:
intent: List agent skills
effect: read
questions:
- What skills are available to my agents, built-in and custom?
- Can I include skills that came from installed plugins in the list?
instructions:
- text: List all Agent Builder skills.
- text: List skills including those provided by plugins.
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills'].post
update:
x-apievangelist-phrasing:
intent: Create a custom skill
effect: write
questions:
- How do I write my own skill for Agent Builder agents?
- Can a new skill reference specific tools?
instructions:
- text: Create skill {id} named {name}, described as {description}, with content {content}.
slots:
id: requestBody.id
name: requestBody.name
description: requestBody.description
content: requestBody.content
- text: Add a skill {name} whose content is {content} and that uses tools {tool_ids}.
slots:
name: requestBody.name
content: requestBody.content
tool_ids: requestBody.tool_ids
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].get
update:
x-apievangelist-phrasing:
intent: Get a skill
effect: read
questions:
- What content and tools does a particular skill define?
- Can I fetch one skill by its id?
instructions:
- text: Get skill {skillId}.
slots:
skillId: path.skillId
- text: Show the content of skill {skillId}.
slots:
skillId: path.skillId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].put
update:
x-apievangelist-phrasing:
intent: Update a custom skill
effect: write
questions:
- Can I edit a skill I created earlier?
- Is it possible to change the tools a user-created skill uses?
instructions:
- text: Update skill {skillId} with new content {content}.
slots:
skillId: path.skillId
content: requestBody.content
- text: Change the tools used by skill {skillId} to {tool_ids}.
slots:
skillId: path.skillId
tool_ids: requestBody.tool_ids
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/skills/{skillId}'].delete
update:
x-apievangelist-phrasing:
intent: Delete a custom skill
effect: destructive
questions:
- What happens if I delete a skill that agents still reference?
- Can built-in skills be deleted?
instructions:
- text: Delete skill {skillId}.
slots:
skillId: path.skillId
- text: Force delete skill {skillId} and detach it from any agents.
slots:
skillId: path.skillId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools'].get
update:
x-apievangelist-phrasing:
intent: List agent tools
effect: read
questions:
- Which tools can my Agent Builder agents call?
- Can I see each tool's schema and configuration requirements?
instructions:
- text: List all Agent Builder tools.
- text: Show every available tool with its schema.
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools'].post
update:
x-apievangelist-phrasing:
intent: Create a custom tool
effect: write
questions:
- How do I define a custom tool for my agents to use?
- Can I require confirmation before an agent runs a tool I create?
instructions:
- text: Create a {type} tool with id {tool_id} and configuration {configuration}.
slots:
type: requestBody.type
tool_id: requestBody.id
configuration: requestBody.configuration
- text: Create tool {tool_id} of type {type}, tagged {tags}, with configuration {configuration}.
slots:
tool_id: requestBody.id
type: requestBody.type
tags: requestBody.tags
configuration: requestBody.configuration
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/_execute'].post
update:
x-apievangelist-phrasing:
intent: Run a tool directly
effect: write
questions:
- 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?
instructions:
- text: Run tool {tool_id} with parameters {tool_params}.
slots:
tool_id: requestBody.tool_id
tool_params: requestBody.tool_params
- text: Execute tool {tool_id} with {tool_params} using connector {connector_id}.
slots:
tool_id: requestBody.tool_id
tool_params: requestBody.tool_params
connector_id: requestBody.connector_id
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].get
update:
x-apievangelist-phrasing:
intent: Get a tool's definition
effect: read
questions:
- What parameters and configuration does one particular tool expect?
- Can I retrieve a single tool definition by id?
instructions:
- text: Get the definition of tool {toolId}.
slots:
toolId: path.toolId
- text: Show the schema for tool {toolId}.
slots:
toolId: path.toolId
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].put
update:
x-apievangelist-phrasing:
intent: Update a tool
effect: write
questions:
- Can I change the configuration of a tool that already exists?
- How do I retag or redescribe an existing tool?
instructions:
- text: Update tool {toolId} with configuration {configuration}.
slots:
toolId: path.toolId
configuration: requestBody.configuration
- text: Set the tags on tool {toolId} to {tags}.
slots:
toolId: path.toolId
tags: requestBody.tags
method: generated
generated: '2026-09-26'
- target: $.paths['/api/agent_builder/tools/{toolId}'].delete
update:
x-apievangelist-phrasing:
intent: Delete a tool
effect: destructive
questions:
- Is deleting a tool from Agent Builder reversible?
- Can I force the removal of a tool agents are still using?
instructions:
- text: Delete tool {toolId}.
slots:
toolId: path.toolId
- text: Force delete tool {toolId} even if agents use it.
slots:
toolId: path.toolId
method: generated
generated: '2026-09-26'