Update an agent

PUT /api/agent_builder/agents/{id}

Spaces method and path for this operation:

put /s/{space_id}/api/agent_builder/agents/{id}

Refer to Spaces for more information.

Update an existing agent configuration. Use this endpoint to modify any aspect of the agent's behavior, appearance, or capabilities. To learn more about agents, refer to the agents documentation.

[Required authorization] Route required privileges: agentBuilder:manageAgents.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The unique identifier of the agent to update.

application/json

Body

access_control object

Additional properties are NOT allowed.
Hide access_control attribute Show access_control attribute object
- access_mode string Required Generally available
  
  Access-control mode: public (any privileged user can read/write), shared (any privileged user can read, only owner can write), private (only owner can read/write). Agents created without an access-control mode default to private.
  
  Values are public, shared, or private.
avatar_color string

Updated hex color code for the agent avatar.
avatar_symbol string

Updated symbol/initials for the agent avatar.
configuration object

Updated configuration settings for the agent.

Additional properties are NOT allowed.
Hide configuration attributes Show configuration attributes object
- ai_indices array[string]
  
  Array of AI indices to associate with the agent.
  
  Not more than 100 elements. Maximum length of each is 256.
- approvals object Generally available
  
  Auto-approval defaults applied to every run of this agent.
  
  Additional properties are NOT allowed.
  Hide approvals attribute Show approvals attribute object
  
  auto_approved_apis object
  
  Destructive Elasticsearch or Kibana APIs this agent may call without a user confirmation, keyed by backend.
  
  Additional properties are NOT allowed.
  
  Hide auto_approved_apis attributes Show auto_approved_apis attributes object
  
  elasticsearch array[string]
  
  Elasticsearch APIs pre-approved for every run of this agent. Each entry is an exact identifier formed from the namespace and name (for example indices.create), a namespace wildcard (for example indices.*), or * for every Elasticsearch API. Entries are not checked against the known APIs, and one that matches no API has no effect.
  
  Not more than 100 elements. Maximum length of each is 256.
  
  kibana array[string]
  
  Kibana APIs pre-approved for every run of this agent. Each entry is an exact identifier formed from the namespace and name (for example alerting.delete-alerting-rule-id), a namespace wildcard (for example alerting.*), or * for every Kibana API. Entries are not checked against the known APIs, and one that matches no API has no effect.
  
  Not more than 100 elements. Maximum length of each is 256.
- connector_ids array[string]
  
  Array of connector IDs to associate with the agent.
  
  Not more than 100 elements.
- enable_elastic_capabilities boolean
  
  When true, enables built-in Elastic capabilities for the agent.
- instructions string
  
  Updated system instructions that define the agent behavior.
- plugin_ids array[string]
  
  Array of plugin IDs to assign to the agent.
  
  Not more than 100 elements.
- post_execution_workflow_ids array[string]
  
  Updated list of workflow IDs. When set, these workflows run after the agent finishes each round.
  
  Not more than 100 elements. Maximum length of each is 512.
- skill_ids array[string]
  
  Array of skill IDs to be available to the agent.
  
  Not more than 100 elements.
- subagent_ids array[string] Generally available
  
  Allowlist of subagent IDs this agent may spawn. Missing or empty disables the run_subagent tool. Use '_self' to enable self-fork.
  
  Not more than 50 elements. Maximum length of each is 64.
- tools array[object]
  
  Tool selection configuration for the agent.
  Hide tools attribute Show tools attribute object
  
  Tool selection configuration for the agent.
  
  tool_ids array[string] Required
  
  Array of tool IDs that the agent can use.
- workflow_ids array[string]
  
  Updated list of workflow IDs. When set, these workflows run every agent execution, in order.
  
  Not more than 100 elements.
description string

Updated description of what the agent does.
labels array[string]

Updated labels for categorizing and organizing agents.
name string

Updated display name for the agent.

Responses

200 application/json

Indicates a successful response

PUT /api/agent_builder/agents/{id}

curl \
  -X PUT "${KIBANA_URL}/api/agent_builder/agents/{id}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search Index Helper",
    "description": "Updated description - Search for anything in \"content-*\" indices!",
    "labels": ["custom-indices", "department-search", "elastic-employees"],
    "avatar_color": "#BFDBFF",
    "avatar_symbol": "SI",
    "configuration": {
      "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
      "tools": [{
        "tool_ids": [
          "platform.core.search",
          "platform.core.list_indices",
          "platform.core.get_index_mapping",
          "platform.core.get_document_by_id"
        ]
      }]
    }
  }'

PUT kbn://api/agent_builder/agents/{id}
{
  "name": "Search Index Helper",
  "description": "Updated description - Search for anything in \"content-*\" indices!",
  "labels": ["custom-indices", "department-search", "elastic-employees"],
  "avatar_color": "#BFDBFF",
  "avatar_symbol": "SI",
  "configuration": {
    "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
    "tools": [{
      "tool_ids": [
        "platform.core.search",
        "platform.core.list_indices",
        "platform.core.get_index_mapping",
        "platform.core.get_document_by_id"
      ]
    }]
  }
}

Request example

Example request for updating custom agent

{
  "avatar_color": "#BFDBFF",
  "avatar_symbol": "SI",
  "configuration": {
    "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
    "tools": [
      {
        "tool_ids": [
          "platform.core.search",
          "platform.core.list_indices",
          "platform.core.get_index_mapping",
          "platform.core.get_document_by_id"
        ]
      }
    ]
  },
  "description": "Updated description - Search for anything in \"content-*\" indices!",
  "id": "created-agent-id",
  "labels": [
    "custom-indices",
    "department-search",
    "elastic-employees"
  ],
  "name": "Search Index Helper"
}

Response examples (200)

Example response returning the agent definition with the changes applied from the request

{
  "avatar_color": "#BFDBFF",
  "avatar_symbol": "SI",
  "configuration": {
    "instructions": "You are a custom agent that wants to help searching data using all indices starting with prefix \"content-\".",
    "tools": [
      {
        "tool_ids": [
          "platform.core.search",
          "platform.core.list_indices",
          "platform.core.get_index_mapping",
          "platform.core.get_document_by_id"
        ]
      }
    ]
  },
  "description": "Updated description - Search for anything in \"content-*\" indices!",
  "id": "created-agent-id",
  "labels": [
    "custom-indices",
    "department-search",
    "elastic-employees"
  ],
  "name": "Search Index Helper",
  "type": "chat"
}