microsoft/semantic-kernel · error · AgentInitializationException

Missing or malformed 'vector_store_ids' in: {spec}

Error message

Missing or malformed 'vector_store_ids' in: {spec}

What it means

Raised by the registered 'file_search' tool builder in openai_responses_agent when a file_search tool spec's options.vector_store_ids is missing, not a list, or an empty/None-first-element list. The Responses file_search tool requires at least one valid vector store id, so the builder validates before calling configure_file_search_tool.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_responses_agent.py:96

# region Declarative Spec

_TOOL_BUILDERS: dict[str, Callable[[ToolSpec, Kernel | None], ToolParam]] = {}


def _register_tool(tool_type: str):
    def decorator(fn: Callable[[ToolSpec, Kernel | None], ToolParam]):
        _TOOL_BUILDERS[tool_type.lower()] = fn
        return fn

    return decorator


@_register_tool("file_search")
def _file_search(spec: ToolSpec, kernel: Kernel | None = None) -> FileSearchToolParam:
    options = spec.options or {}
    vector_store_ids = options.get("vector_store_ids")
    if not vector_store_ids or not isinstance(vector_store_ids, list) or not vector_store_ids[0]:
        raise AgentInitializationException(f"Missing or malformed 'vector_store_ids' in: {spec}")

    filters = options.get("filters")
    max_num_results = options.get("max_num_results")
    ranking_options = options.get("ranking_options", {})
    score_threshold = ranking_options.get("score_threshold")
    ranker = ranking_options.get("ranker")

    return OpenAIResponsesAgent.configure_file_search_tool(
        vector_store_ids=vector_store_ids,
        filters=filters,
        max_num_results=max_num_results,
        score_threshold=score_threshold,
        ranker=ranker,
    )


@_register_tool("web_search")
def _web_search(spec: ToolSpec, kernel: Kernel | None = None) -> WebSearchToolParam:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide options={'vector_store_ids': ['vs_xxx']} with a non-empty list of valid store ids.
2. Create the vector store first (client.vector_stores.create) and use the returned id.
3. Validate spec.options['vector_store_ids'] is a non-empty list of strings before building tools.

Example fix

# before
tool_spec = {'type':'file_search','options':{'vector_store_ids': None}}

# after
tool_spec = {'type':'file_search','options':{'vector_store_ids': ['vs_abc123']}}

opts = spec.get('options', {})
vs = opts.get('vector_store_ids')
assert isinstance(vs, list) and vs and vs[0], 'vector_store_ids must be a non-empty list'

def has_valid_vector_store_ids(spec: dict) -> bool:
    vs = (spec.get('options') or {}).get('vector_store_ids')
    return isinstance(vs, list) and bool(vs and vs[0])

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    tool = _build_tool(tool_spec, kernel)
except AgentInitializationException as e:
    if 'vector_store_ids' in str(e):
        tool_spec['options']['vector_store_ids'] = [vs_id]
        tool = _build_tool(tool_spec, kernel)

When it happens

Trigger: A declarative tool spec of type 'file_search' with options lacking 'vector_store_ids', with it set to None, a single string instead of a list, or a list whose first entry is falsy; building tools from a YAML spec where the field is misnamed.

Common situations: YAML tool config missing vector_store_ids; passing a string id where a list is expected; vector store not yet created so the id is empty; key typo (vectorStoreIds vs vector_store_ids).

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Tool spec must include a 'type' field.
• Unsupported tool type: {spec.type}
• AI Chat Service type '{appConfig.RagConfig.AIChatService}' i
• AI Embedding Service type '{appConfig.RagConfig.AIEmbeddingS
• Vector store type '{appConfig.RagConfig.VectorStoreType}' is

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/4a4a63370917a038. Report an issue: GitHub.