Semantic Search tool

Use Semantic Search when you want the assistant to retrieve information from previously ingested artifacts (documents, notes, PDFs, HTML, and more).

Prerequisites

An API token. See Backoffice Developer Console.
Ingested artifacts to search (see Artifacts).

Requirements

Tool spec: { "name": "semantic_search", "type": "semantic_search_v1" }
tool_context: at least one ingested_artifact with a context_filter

Basic request and response

This example validates a request that enables semantic search over a collection:

curl -X POST "https://{BASE_URL}/api/gpt/v1/messages/validate" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "max_tokens": 128,
    "messages": [
      { "role": "user", "content": "What shipped in the latest billing dashboard release?" }
    ],
    "tools": [
      { "name": "semantic_search", "type": "semantic_search_v1" }
    ],
    "tool_choice": { "type": "auto" },
    "tool_context": [
      {
        "type": "ingested_artifact",
        "context_filter": {
          "collection": "{collectionID}"
        }
      }
    ]
  }'

Example response:

{ "valid": true, "errors": null }

To run the request, send the same body to POST /messages.

Response blocks

Zylon runs this tool on the server. The response contains a server_tool_use block with the call, followed by a server_tool_result block with the result. The call ID starts with srvtoolu_. Don’t send a tool_result back for it.

[
  { "type": "server_tool_use", "id": "srvtoolu_9c0d", "name": "semantic_search", "input": { "query": "billing dashboard release" } },
  {
    "type": "server_tool_result",
    "tool_use_id": "srvtoolu_9c0d",
    "content": [
      { "type": "source", "sources": [{ "object": "context.chunk", "id": "chunk_1", "text": "The billing dashboard release added invoice exports..." }] },
      { "type": "text", "text": "The billing dashboard release added invoice exports and fixed three bugs." }
    ],
    "is_error": false
  }
]

source blocks are Zylon-specific. They are returned only when the Zylon extension is enabled. Error:

{ "type": "server_tool_result", "tool_use_id": "srvtoolu_9c0d", "content": "context_filter is required", "is_error": true }

is_error is true when the tool fails, and content holds the error message. See Migrating from 1.57 to 1.58 for the full list of server tool blocks.

Tips

Keep tool_context narrow (use a single collection and the smallest set of artifacts you need).
If you’re not getting relevant results, ingest cleaner source text (or split large documents into smaller artifacts).

Next steps

Ingest and manage artifacts: Artifacts
Learn how messages return tool blocks: Messages

First Steps

Build with Zylon

Coding Agents

Semantic Search tool

Prerequisites

Requirements

Basic request and response

Response blocks

Tips

Next steps

​Prerequisites

​Requirements

​Basic request and response

​Response blocks

​Tips

​Next steps

Prerequisites

Requirements

Basic request and response

Response blocks

Tips

Next steps