Kibana Agent Builder

Manage Agent Builder Agents and Tools in Kibana

Create, update, delete, inspect, and chat with Agent Builder agents. Create, update, delete, list, and test custom tools (ES|QL, index search, workflow). If the user provided a name, use $ARGUMENTS as the default agent name.

Prerequisites

Set these environment variables before running any script:

Provide either KIBANA_API_KEY or KIBANA_USERNAME + KIBANA_PASSWORD.

Agent Management

Create an Agent

Step 1: List available tools

node skills/kibana/agent-builder/scripts/agent-builder.js list-tools

If the script reports a connection error, stop and tell the user to verify their KIBANA_URL and authentication environment variables.

Review the list of available tools. Tools prefixed with platform.core. are built-in. Other tools are custom or connector-provided.

Step 2: List existing agents

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

This helps avoid name conflicts and shows what is already configured.

Step 3: Gather agent details

Using $ARGUMENTS as the default name, confirm or collect from the user:

1. Name (required) — The agent's display name. Default: $ARGUMENTS. 2. Description (optional) — Brief description of what the agent does. Default: same as name. 3. System instructions (optional) — Custom system prompt for the agent. Default: none.

Step 4: Select tools

Present the available tools from Step 1 and ask the user which ones to include. Suggest a reasonable default based on the agent's purpose. Let the user add or remove tools from the suggested list.

Step 5: Create the agent

node skills/kibana/agent-builder/scripts/agent-builder.js create-agent \
  --name "<agent_name>" \
  --description "<description>" \
  --instructions "<system_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>,<tool_id_3>"

Where:

• --name is required
• --tool-ids is a comma-separated list of tool IDs from Step 4
• --description defaults to the name if omitted
• --instructions can be omitted if the user did not provide any

Step 6: Verify creation

node skills/kibana/agent-builder/scripts/agent-builder.js list-agents

Show the user the newly created agent entry. If it appears, report success. If not, show any error output from Step 5.

Get an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js get-agent --id "<agent_id>"

Update an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js update-agent \
  --id "<agent_id>" \
  --description "<new_description>" \
  --instructions "<new_instructions>" \
  --tool-ids "<tool_id_1>,<tool_id_2>"

All flags except --id are optional — only provided fields are updated. The agent's id and name are immutable.

API constraint: PUT only accepts description, configuration, and tags. Including id, name, or type

causes a 400 error.

Delete an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js delete-agent --id "<agent_id>"

Always confirm with the user before deleting. Deletion is permanent.

Chat with an Agent

node skills/kibana/agent-builder/scripts/agent-builder.js chat \
  --id "<agent_id>" \
  --message "<user_message>"

Uses the streaming endpoint POST /api/agent_builder/converse/async with agent_id and input in the request body. Output shows [Reasoning], [Tool Call], [Tool Result], and [Response] as events arrive. Pass --conversation-id to continue an existing conversation.

Note: This command may take 30-60 seconds as the agent reasons and calls tools. Use a longer timeout (e.g., 120s or 180s) when running via Bash.

Tool Management

Custom tools extend what agents can do beyond the built-in platform tools.

Tool Types

ES|QL Tools

Pre-defined, parameterized ES|QL queries. Use when you need guaranteed query correctness, enforced business rules, analytics aggregations, or fine-grained data access control.

Parameter syntax: Use ?param_name in the query. Define each parameter with type and description only. Valid types: string, integer, float, boolean, date, array.

{
  "id": "campaign_revenue_by_region",
  "type": "esql",
  "description": "Calculates confirmed revenue for a region by quarter.",
  "configuration": {
    "query": "FROM finance-orders-* | WHERE order_status == \"completed\" AND region == ?region | STATS total_revenue = SUM(amount) BY quarter | LIMIT 10",
    "params": {
      "region": {
        "type": "string",
        "description": "Region code, e.g. 'US', 'EU', 'APAC'"
      }
    }
  }
}

Index Search Tools

Scope the built-in search capability to a specific index pattern. The LLM decides how to query; you control which indices are accessible.

{
  "id": "customer_feedback_search",
  "type": "index_search",
  "description": "Searches customer feedback and support tickets.",
  "configuration": {
    "pattern": "customer-feedback-*"
  }
}

Workflow Tools

Connect an agent to an Elastic Workflow — a YAML-defined multi-step automation. Use when the agent needs to take action beyond data retrieval (send notifications, create tickets, call external APIs).

{
  "id": "investigate-alert-workflow",
  "type": "workflow",
  "description": "Triggers automated alert investigation.",
  "configuration": {
    "workflow_id": "security-alert-investigation"
  }
}

Parameters are auto-detected from the workflow's inputs section.

Tool API Constraints

Read these before creating tools — violations cause 400 errors.

• POST body fields: Only id, type, description, configuration, and tags are accepted. name is not a

valid field — omit it entirely.

• `params` is always required for ES|QL tools, even when empty — use "params": {}.
• Param fields: Only type and description are accepted per parameter. default and optional are not valid

and cause 400 errors. Hard-code sensible defaults in the query instead.

• Index search config: Use "pattern", not "index". Using "index" causes a validation error.
• PUT restrictions: Only description, configuration, and tags are accepted. Including id or type causes a

400 error — these fields are immutable after creation.

Tool Script Commands

List all tools

node skills/kibana/agent-builder/scripts/agent-builder.js list-custom-tools

Get a specific tool

node skills/kibana/agent-builder/scripts/agent-builder.js get-tool --id "<tool_id>"

Create a tool

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "esql" \
  --description "<description>" \
  --query "<esql_query>" \
  --params '{"region": {"type": "string", "description": "Region code"}}'

For index search tools:

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "index_search" \
  --description "<description>" \
  --pattern "my-index-*"

For workflow tools:

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "<tool_id>" \
  --type "workflow" \
  --description "<description>" \
  --workflow-id "my-workflow-name"

Update a tool

node skills/kibana/agent-builder/scripts/agent-builder.js update-tool \
  --id "<tool_id>" \
  --description "<new_description>" \
  --query "<new_query>"

Only description, configuration, and tags can be updated. id and type are immutable.

Delete a tool

node skills/kibana/agent-builder/scripts/agent-builder.js delete-tool --id "<tool_id>"

Test a tool

node skills/kibana/agent-builder/scripts/agent-builder.js test-tool \
  --id "<tool_id>" \
  --params '{"region": "US"}'

Executes the tool via POST /api/agent_builder/tools/_execute and displays column names and row counts for ES|QL results.

Examples

Create an agent

User: /kibana-agent-builder sales-helper

1. List tools — finds platform.core.search, platform.core.list_indices, and a custom esql-sales-data tool 2. List agents — no conflicts 3. Name: "sales-helper", Description: "Helps query sales data" 4. Tools: esql-sales-data, platform.core.search, platform.core.list_indices 5. Create with --name "sales-helper" --tool-ids "esql-sales-data,platform.core.search,platform.core.list_indices" 6. Verify — agent appears in list

Update an agent's instructions

User: Update the sales-helper agent to focus on the APAC region

1. Get agent — get-agent --id "sales-helper" to see current config 2. Update — update-agent --id "sales-helper" --instructions "Focus on APAC sales data. Use esql-sales-data for queries." 3. Verify — get-agent --id "sales-helper" to confirm new instructions

Chat with an agent

User: Ask sales-helper what the top revenue products are

1. Chat — chat --id "sales-helper" --message "What are the top revenue products?" 2. Display the agent's response

Create an ES|QL tool with parameters

User: Create a tool that shows billing complaints by category for the last N days

1. Consult the elasticsearch-esql skill for ES|QL syntax 2. Create tool:

   node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
     --id "billing_complaint_summary" \
     --type "esql" \
     --description "Returns billing complaints grouped by sub-category for the last N days." \
     --query "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?days::integer * 1d AND MATCH(feedback_text, 'billing') | STATS count = COUNT(*) BY sub_category | SORT count DESC | LIMIT 10" \
     --params '{"days": {"type": "integer", "description": "Number of days to look back"}}'

3. Test: test-tool --id "billing_complaint_summary" --params '{"days": 30}'

Create an index search tool

User: Create a tool to search support transcripts

node skills/kibana/agent-builder/scripts/agent-builder.js create-tool \
  --id "transcript_search" \
  --type "index_search" \
  --description "Searches support call transcripts by topic, agent, or customer issue." \
  --pattern "support-transcripts"

References

Read these for detailed guidance:

• references/architecture-guide.md — Core concepts, built-in tools, context engineering, best practices, token

optimization, REST API endpoints, MCP/A2A integration, permissions

• references/use-cases.md — Full playbooks for Customer Feedback Analysis, Marketing Campaign Analysis, and Contract

Analysis agents

For ES|QL syntax, functions, operators, and parameter rules, use the elasticsearch-esql skill. For workflow YAML structure, trigger types, step types, and agent-workflow patterns, use the security-workflows skill.

Guidelines

• Always run list-tools before creating an agent so the user can choose from real, available tools.
• Always run list-agents before and after creation to detect conflicts and verify success.
• Do not invent tool IDs — only use IDs returned by list-tools.
• If no custom tools exist yet, suggest creating one or using the built-in platform tools.
• The agent ID is auto-generated from the name (lowercased, hyphens, alphanumeric only).
• For non-default Kibana spaces, set KIBANA_SPACE_ID before running the script.
• Confirm with the user before running delete-agent or delete-tool — deletion is permanent.
• Always include | LIMIT N in ES|QL queries to prevent context window overflow.
• Write descriptive tool descriptions — the agent decides which tool to call based solely on the description.
• Scope index search tools narrowly (e.g., customer-feedback-* not *).
• Use KEEP to return only needed columns and reduce token consumption.
• Validate ES|QL queries with test-tool before assigning to an agent.
• For ES|QL tools with no parameters, still include "params": {}.

Elastic Agent Builder Architecture Guide

Elastic Agent Builder is a framework built into Elasticsearch/Kibana that creates AI agents grounded in your Elasticsearch data. It combines LLMs with Elasticsearch's search, analytics, and relevance capabilities into a unified platform — no separate vector database, RAG pipeline, or tool orchestrator needed.

Docs: Elastic Agent Builder

Core Concepts

Three Building Blocks

1. Chat UI — A real-time conversational interface (in Kibana or via API) to interact with agents.

2. Agents — LLM-powered entities that follow custom instructions and use tools to answer questions, run analytics, or drive workflows. Two flavors:

• Built-in agents — Pre-configured, ready to chat with your data immediately
• Custom agents — User-defined system prompt + curated toolset + security profile

3. Tools — Modular, reusable functions agents invoke to retrieve or manipulate data. Two flavors:

• Built-in tools (prefixed platform.core.*) — Ship out of the box
• Custom tools — ES|QL tools, index search tools, or workflow tools you define

Built-in Tools Reference

platform.core.search is the primary context retrieval tool — it handles hybrid search automatically (lexical + semantic via ELSER/dense vectors), selecting the right index and query type.

Elasticsearch as a Context Engine

Agent Builder leverages Elasticsearch natively for three context engineering patterns:

1. Improving Context Management

• platform.core.search auto-selects the best index and translates natural language into optimized queries, preventing

context window overflow

• Use index search tools scoped to specific indices to restrict the agent's surface area and reduce noise
• Use platform.core.index_explorer in multi-index environments to route queries to the right data source
• Instruct agents explicitly in their system prompt to use tools rather than rely on training knowledge

2. Persistent Memory Layer

Elasticsearch naturally acts as long-term memory:

• Short-term memory: Agent Builder's built-in chat session tracks conversation history automatically
• Long-term memory: Store agent outputs back to Elasticsearch indices for retrieval in future sessions
• Cross-session context: Index tool outputs to a dedicated memory index, then give the agent an index search tool

scoped to that index to retrieve past reasoning

• Elastic Workflows can automate the write-back of outputs to memory indices

3. Hybrid Search for Relevance

platform.core.search and custom index search tools use Elasticsearch's full hybrid search stack:

• Lexical (BM25) for keyword precision
• Semantic/vector (ELSER sparse vectors or dense embeddings) for conceptual matching
• FORK/FUSE in ES|QL combines multiple search strategies using Reciprocal Rank Fusion (RRF)
• Reranking with Elastic Rerank or third-party models (Cohere, Vertex) for final relevance scoring
• Use semantic_text field type to enable out-of-the-box semantic search without managing embeddings manually

Best Practices

Tool Design

• Write descriptive tool descriptions — The agent decides which tool to call based solely on the description. Be

explicit about when to use each tool and include example trigger phrases.

• Scope index search tools narrowly — Prefer customer-feedback-* over * to reduce noise and limit token

consumption from oversized result sets.

• Include LIMIT in every ES|QL query — The implicit default is 1000 rows, which consumes tokens rapidly and can

trigger context_length_exceeded errors.

• Validate ES|QL before deploying — Use the "Infer parameters from query" button in Kibana UI to auto-detect

parameters and test with sample values.

• Add `_meta.description` to index mappings — Helps platform.core.search and platform.core.index_explorer select

the right index without calling list_indices first.

Agent Prompt Design

• Explicitly instruct tool use — LLMs sometimes answer from training data instead of calling tools. Add: "Always use

tools to retrieve data. Never answer data questions from memory."

• Name which tool to use for which intent — Vague instructions lead to wrong tool selection. Be specific: "For

sentiment trends, use feedback_sentiment_trend. For individual feedback, use customer_feedback_search."

• Instruct the agent to ask for clarification — Prevents broad queries when a targeted tool would suffice: "If the

user's question is ambiguous about time range, ask for clarification before querying."

Token Optimization

Token costs accumulate from conversation history, tool response payloads, and the number of tool calls per turn.

• Replace broad built-in tools with focused custom tools — Custom tools pre-define the query logic and scope, so the

LLM only controls parameters, not the query shape. This produces smaller, more relevant result sets.

• Limit the toolset assigned to each agent — Every tool in an agent's toolset is included in the system prompt as a

function definition, consuming input tokens on every call — even unused tools. Design agents with the minimum viable toolset.

• Use agent instructions to enforce tool discipline — Even with a focused toolset, an agent may call tools

redundantly. Use the system prompt to create explicit call rules: "For trend questions, ALWAYS use billing_complaint_summary. Do NOT call more than one tool per user question unless the question explicitly asks for two things."

• Keep tool responses small — Use KEEP to return only needed columns. Prefer aggregations over raw document

retrieval for summary questions.

• Monitor token usage — Agent Builder displays input and output token counts after each response in the Chat UI. Use

the "View JSON" button to inspect the raw usage breakdown per tool call.

Docs: Monitor usage

Troubleshooting:

Context length exceeded

Programmatic Access

REST API Base Path

/api/agent_builder/

For Kibana Spaces: /s/<space_name>/api/agent_builder/

Key Endpoints

MCP & A2A Integration

• MCP server: Exposes all built-in and custom tools to any MCP client (Claude Desktop, Cursor, VS Code). Provide

your Kibana URL + API key in the client config.

• A2A server: Exposes agents to external agent frameworks, services, and apps — enabling reuse of your Elastic

context engineering logic across integrations.

Permissions & Security

• Tools and agents respect Elasticsearch RBAC — the API key used scopes what data is accessible
• MCP and A2A support OAuth and custom authentication mechanisms
• Custom ES|QL tools provide guardrails by pre-defining query structure — only parameters are LLM-controlled, not query

logic

Elastic Agent Builder — Use Case Playbooks

---

1. Customer Feedback Analysis Agent

Goal: Analyze customer feedback, identify sentiment trends, surface policy-related mentions, and generate analytics.

Key Tools:

• platform.core.search — semantic search over feedback indices for open-ended queries
• Custom Index Search tool scoped to customer-feedback-* — focused retrieval
• Custom ES|QL tool for sentiment aggregations and trend analytics

Custom Index Search Tool

POST /api/agent_builder/tools

{
  "id": "customer_feedback_search",
  "type": "index_search",
  "description": "Searches customer feedback, support tickets, and NPS responses. Use this to find sentiment, product complaints, praise, or policy mentions. Supports semantic and keyword search.",
  "configuration": {
    "pattern": "customer-feedback-*"
  }
}

Custom ES|QL Tool — Sentiment Trend by Product

POST /api/agent_builder/tools

{
  "id": "feedback_sentiment_trend",
  "type": "esql",
  "description": "Returns a breakdown of positive vs. negative feedback counts by product category over a given number of days. Use for trend analysis, not for reading individual feedback.",
  "configuration": {
    "query": "FROM customer-feedback-* | WHERE @timestamp >= NOW() - ?lookback_days::integer * 1d | STATS positive = COUNT(*) WHERE sentiment == \"positive\", negative = COUNT(*) WHERE sentiment == \"negative\", total = COUNT(*) BY product_category | SORT negative DESC | LIMIT 20",
    "params": {
      "lookback_days": {
        "type": "integer",
        "description": "Number of days to look back, e.g. 7, 30, 90"
      }
    }
  }
}

Custom ES|QL Tool — Policy Compliance Check

POST /api/agent_builder/tools

{
  "id": "policy_mention_search",
  "type": "esql",
  "description": "Counts how many feedback items mention a specific policy keyword. Use for compliance monitoring or to understand which policies generate the most customer friction.",
  "configuration": {
    "query": "FROM customer-feedback-* | WHERE MATCH(feedback_text, ?policy_keyword) | STATS mention_count = COUNT(*), avg_sentiment_score = AVG(sentiment_score) BY product_category | SORT mention_count DESC | LIMIT 15",
    "params": {
      "policy_keyword": {
        "type": "string",
        "description": "Policy term or keyword to search for, e.g. 'refund policy', 'cancellation', 'data privacy'"
      }
    }
  }
}

Agent Definition

POST /api/agent_builder/agents

{
  "id": "customer-feedback-agent",
  "name": "Customer Feedback Analyst",
  "description": "Analyzes customer sentiment, surfaces policy friction points, and provides product feedback trends.",
  "configuration": {
    "instructions": "You are a customer intelligence analyst. Always use tools to ground your responses in real data — do not answer from memory. For open questions about specific feedback, use customer_feedback_search. For trend analytics or policy mentions, use the ES|QL tools. When presenting findings, include counts and percentages where available.",
    "tools": [
      {
        "tool_ids": [
          "customer_feedback_search",
          "feedback_sentiment_trend",
          "policy_mention_search",
          "platform.core.search"
        ]
      }
    ]
  }
}

---

2. Marketing Campaign Analysis Agent

Goal: Analyze campaign performance, compare results across campaigns, and join campaign metadata with outcome data using ES|QL LOOKUP JOIN.

Key Tools:

• platform.core.search — broad semantic retrieval across marketing indices
• Custom Index Search tool scoped to campaign description indices
• Custom ES|QL tools that join campaign description + results indices

Custom Index Search Tool — Campaign Descriptions

POST /api/agent_builder/tools

{
  "id": "campaign_description_search",
  "type": "index_search",
  "description": "Search marketing campaign descriptions, objectives, target audiences, and creative briefs. Use to understand what a campaign was about or find campaigns matching specific criteria.",
  "configuration": {
    "pattern": "marketing-campaigns-*"
  }
}

Custom ES|QL Tool — Campaign Performance Join

POST /api/agent_builder/tools

{
  "id": "campaign_performance_analysis",
  "type": "esql",
  "description": "Joins campaign descriptions with performance results to analyze ROI, conversion rates, and spend efficiency for campaigns in a given channel over a lookback period. Use when the user asks about campaign effectiveness, ROI, or performance comparisons.",
  "configuration": {
    "query": "FROM marketing-campaign-results-* | WHERE channel == ?channel AND @timestamp >= NOW() - ?lookback_days::integer * 1d | STATS total_spend = SUM(spend), total_conversions = SUM(conversions), total_impressions = SUM(impressions), avg_ctr = AVG(click_through_rate) BY campaign_id | LOOKUP JOIN marketing-campaigns-* ON campaign_id | EVAL roi = (total_conversions * ?revenue_per_conversion - total_spend) / total_spend * 100 | SORT roi DESC | LIMIT 10",
    "params": {
      "channel": {
        "type": "string",
        "description": "Marketing channel, e.g. 'email', 'social', 'paid_search', 'display'"
      },
      "lookback_days": {
        "type": "integer",
        "description": "Number of days to look back, e.g. 30, 90, 365"
      },
      "revenue_per_conversion": {
        "type": "float",
        "description": "Assumed revenue value per conversion for ROI calculation"
      }
    }
  }
}

Custom ES|QL Tool — Audience Segment Performance

POST /api/agent_builder/tools

{
  "id": "audience_segment_performance",
  "type": "esql",
  "description": "Analyzes which audience segments perform best for a given campaign. Use when the user asks about targeting effectiveness or audience insights.",
  "configuration": {
    "query": "FROM marketing-campaign-results-* | WHERE campaign_id == ?campaign_id | STATS conversions = SUM(conversions), spend = SUM(spend), impressions = SUM(impressions) BY audience_segment | EVAL cost_per_conversion = spend / conversions | SORT conversions DESC | LIMIT 15",
    "params": {
      "campaign_id": {
        "type": "string",
        "description": "The campaign ID to analyze"
      }
    }
  }
}

Agent Definition

POST /api/agent_builder/agents

{
  "id": "marketing-campaign-agent",
  "name": "Marketing Campaign Analyst",
  "description": "Analyzes marketing campaign effectiveness, compares ROI across campaigns and channels, and surfaces audience insights.",
  "configuration": {
    "instructions": "You are a marketing analytics expert. Always call tools for data — never answer from memory. For qualitative questions about what a campaign was about, use campaign_description_search. For performance metrics and ROI, use campaign_performance_analysis. For audience breakdowns, use audience_segment_performance. When showing results, present a concise summary with the most important metrics highlighted, then offer to drill down further.",
    "tools": [
      {
        "tool_ids": [
          "campaign_description_search",
          "campaign_performance_analysis",
          "audience_segment_performance",
          "platform.core.search"
        ]
      }
    ]
  }
}

---

3. Contract Analysis Agent

Goal: Search a large corpus of contracts for specific clause mentions, identify non-standard terms, and surface risk patterns using hybrid search + ES|QL analytics.

Key Design: Hybrid search finds contracts with relevant clauses (using semantic + lexical matching). ES|QL tools then extract and analyze specific term patterns across the corpus.

Custom Index Search Tool — Contract Hybrid Search

POST /api/agent_builder/tools

{
  "id": "contract_search",
  "type": "index_search",
  "description": "Searches the full contract corpus using hybrid search (semantic + keyword). Use to find contracts mentioning specific clauses, obligations, parties, or terms.",
  "configuration": {
    "pattern": "contracts-*"
  }
}

Custom ES|QL Tool — Clause Frequency Analysis

POST /api/agent_builder/tools

{
  "id": "clause_frequency_analysis",
  "type": "esql",
  "description": "Counts how many contracts contain a specific clause or term keyword, grouped by contract type or counterparty category. Use for corpus-wide analysis of how common a clause is.",
  "configuration": {
    "query": "FROM contracts-* | WHERE MATCH(contract_text, ?clause_keyword) | STATS contract_count = COUNT(*), counterparty_types = COUNT_DISTINCT(counterparty_category) BY contract_type | SORT contract_count DESC | LIMIT 20",
    "params": {
      "clause_keyword": {
        "type": "string",
        "description": "Clause or term to search for, e.g. 'limitation of liability', 'force majeure', 'auto-renewal'"
      }
    }
  }
}

Custom ES|QL Tool — Liability Cap Outlier Detection

POST /api/agent_builder/tools

{
  "id": "liability_cap_outliers",
  "type": "esql",
  "description": "Identifies contracts where the liability cap falls significantly above or below the norm for a given contract type. Use to find non-standard commercial terms that may need review.",
  "configuration": {
    "query": "FROM contracts-* | WHERE contract_type == ?contract_type | STATS median_val = MEDIAN(liability_cap_usd), p25 = PERCENTILE(liability_cap_usd, 25), p75 = PERCENTILE(liability_cap_usd, 75) BY contract_type | ENRICH contracts-stats ON contract_type | EVAL low_threshold = p25 * 0.5, high_threshold = p75 * 2.0 | KEEP contract_type, median_val, low_threshold, high_threshold | LIMIT 20",
    "params": {
      "contract_type": {
        "type": "string",
        "description": "Type of contract, e.g. 'vendor', 'customer', 'employment', 'nda'"
      }
    }
  }
}

Note on outlier detection in ES|QL: ES|QL parameters are values only — they cannot be used as dynamic field

references. Design separate tools for each numeric field you want to analyze (e.g., liability_cap_outliers,

payment_terms_outliers). For dynamic outlier detection, use two separate queries (first to compute stats, then to

filter outliers) or pre-compute thresholds into a lookup index.

Custom ES|QL Tool — Expiry & Renewal Risk

POST /api/agent_builder/tools

{
  "id": "contract_expiry_risk",
  "type": "esql",
  "description": "Lists contracts expiring within a specified number of days, including renewal terms and responsible owners. Use for contract lifecycle management or renewal risk analysis.",
  "configuration": {
    "query": "FROM contracts-* | WHERE expiry_date <= NOW() + ?days_ahead::integer * 1d AND expiry_date >= NOW() | STATS count = COUNT(*) BY contract_owner, auto_renewal, contract_type | SORT count DESC | LIMIT 50",
    "params": {
      "days_ahead": {
        "type": "integer",
        "description": "Number of days to look ahead for expiring contracts, e.g. 30, 60, 90"
      }
    }
  }
}

Agent Definition

POST /api/agent_builder/agents

{
  "id": "contract-analysis-agent",
  "name": "Contract Analysis Agent",
  "description": "Searches contract corpus for clause mentions, identifies non-standard terms, and surfaces renewal and risk patterns.",
  "configuration": {
    "instructions": "You are a contract intelligence analyst. Always use tools — never answer from your training data. For finding specific contracts or clauses, use contract_search (hybrid search). For understanding how common a clause is across the corpus, use clause_frequency_analysis. For identifying unusual liability caps, use liability_cap_outliers. For renewal risk, use contract_expiry_risk. When presenting findings, be precise: cite counts, percentages, and specific contract IDs where relevant.",
    "tools": [
      {
        "tool_ids": [
          "contract_search",
          "clause_frequency_analysis",
          "liability_cap_outliers",
          "contract_expiry_risk",
          "platform.core.search"
        ]
      }
    ]
  }
}