AgentBuilderClient¶

Client for the Kibana Agent Builder API.

Agent Builder lets you create and manage AI agents, tools, skills and plugins, chat with agents (with conversation persistence and attachments), and expose agents through the A2A and MCP protocols.

The core Agent Builder APIs (agents, tools, conversations, converse, A2A, MCP) are generally available since Kibana 9.2.0. The attachments, consumption, skills and plugins APIs are in technical preview. Chat-related operations (converse, A2A tasks, MCP tool calls) require a configured LLM connector.

Agent Builder resources are space-scoped: every method accepts an optional space_id to target a specific space.

class kibana._sync.client.agent_builder.AgentBuilderClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Agent Builder API.

Agent Builder lets you create and manage AI agents, tools, skills and plugins, chat with agents (with conversation persistence and attachments), and expose agents through the A2A and MCP protocols.

The core Agent Builder APIs (agents, tools, conversations, converse, A2A, MCP) are generally available since Kibana 9.2.0. The attachments, consumption, skills and plugins APIs are in technical preview (added in 9.2.0-9.4.0). Chat-related operations (converse, A2A tasks, MCP tool calls) require a configured LLM connector.

Agent Builder resources are space-scoped: every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create an ES|QL tool and an agent that can use it
>>> client.agent_builder.create_tool(
...     id="my_ns.lookup",
...     type="esql",
...     description="Look up documents",
...     configuration={"query": "FROM my-index | LIMIT 10", "params": {}},
... )
>>> client.agent_builder.create_agent(
...     id="my-agent",
...     name="My Agent",
...     description="Searches my data",
...     configuration={"tools": [{"tool_ids": ["my_ns.lookup"]}]},
... )
>>>
>>> # Chat with it (requires an LLM connector)
>>> reply = client.agent_builder.converse(
...     input="What data do I have?", agent_id="my-agent"
... )
>>> print(reply.body["response"]["message"])

Tools and Agents

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

# Create an ES|QL tool
client.agent_builder.create_tool(
    id="my_ns.lookup",
    type="esql",
    description="Look up documents",
    configuration={"query": "FROM my-index | LIMIT 10", "params": {}},
)

# Create an agent that can use it
client.agent_builder.create_agent(
    id="my-agent",
    name="My Agent",
    description="Searches my data",
    configuration={"tools": [{"tool_ids": ["my_ns.lookup"]}]},
)

# List agents and tools
agents = client.agent_builder.list_agents()
tools = client.agent_builder.list_tools()
for agent in agents.body["results"]:
    print(agent["id"], agent["name"])

Chatting with Agents

Chat requires a configured LLM connector:

reply = client.agent_builder.converse(
    input="What data do I have?",
    agent_id="my-agent",
)
print(reply.body["response"]["message"])

# Continue an existing conversation
reply = client.agent_builder.converse(
    input="Show me more.",
    agent_id="my-agent",
    conversation_id=reply.body["conversation_id"],
)

# Browse persisted conversations
conversations = client.agent_builder.list_conversations(
    agent_id="my-agent"
)

Executing Tools Directly

result = client.agent_builder.execute_tool(
    tool_id="my_ns.lookup",
    tool_params={},
)

A2A and MCP Protocols

# Fetch the A2A agent card for an agent
card = client.agent_builder.get_a2a_card(agent_id="my-agent")

# Send a JSON-RPC request to the MCP server endpoint
response = client.agent_builder.send_mcp_request(
    payload={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
    }
)

Cleaning Up

client.agent_builder.delete_agent(id="my-agent")
client.agent_builder.delete_tool(tool_id="my_ns.lookup")

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the AgentBuilderClient.

Parameters:

client (Kibana) – The parent Kibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> agent_builder_client = AgentBuilderClient(kibana_client)

list_agents(*, space_id=None, validate_spaces=None)[source]¶

List agents.

GET /api/agent_builder/agents. Generally available; added in 9.2.0. Returns all agents visible to the current user, including the built-in Elastic AI agent.

Parameters:

space_id (str | None) – Optional space ID to list agents from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing a results list of agent definitions (id, type, name, description, configuration, labels, visibility, readonly…).

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

AgentBuilderClient¶

AsyncAgentBuilderClient¶