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 'file_search' tool builder when a ToolSpec's options lack a usable vector_store_ids value. The builder requires a non-empty list whose first element is truthy, because OpenAI file search needs at least one existing vector store id to query.

Source

Thrown at python/semantic_kernel/agents/open_ai/openai_assistant_agent.py:115

        _TOOL_BUILDERS[tool_type.lower()] = fn
        return fn

    return decorator


# Update _code_interpreter
@_register_tool("code_interpreter")
def _code_interpreter(spec: ToolSpec, kernel: Kernel | None = None) -> tuple[list[AssistantToolParam], ToolResources]:
    file_ids = spec.options.get("file_ids")
    return OpenAIAssistantAgent.configure_code_interpreter_tool(file_ids=file_ids)


# Update _file_search
@_register_tool("file_search")
def _file_search(spec: ToolSpec, kernel: Kernel | None = None) -> tuple[list[AssistantToolParam], ToolResources]:
    vector_store_ids = spec.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}")
    return OpenAIAssistantAgent.configure_file_search_tool(vector_store_ids=vector_store_ids)


def _build_tool(spec: ToolSpec, kernel: "Kernel") -> tuple[list[AssistantToolParam], ToolResources]:
    if not spec.type:
        raise AgentInitializationException("Tool spec must include a 'type' field.")

    try:
        builder = _TOOL_BUILDERS[spec.type.lower()]
    except KeyError as exc:
        raise AgentInitializationException(f"Unsupported tool type: {spec.type}") from exc

    sig = inspect.signature(builder)
    return builder(spec) if len(sig.parameters) == 1 else builder(spec, kernel)  # type: ignore[call-arg]


# endregion

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Create the vector store via the OpenAI client and capture the returned id, then pass it as a list.
2. Ensure options={'vector_store_ids': ['vs_abc123']} (a non-empty list with a real id).
3. Validate vector_store_ids is a list and its first element is a non-empty string before building the tool.
4. Check the key spelling is exactly 'vector_store_ids' (snake_case).

Example fix

# before
tool = ToolSpec(type="file_search", options={"vector_store_ids": vs_id})  # vs_id is a str or None
# after
vs = await client.beta.vector_stores.create(name="docs")
tool = ToolSpec(type="file_search", options={"vector_store_ids": [vs.id]})

vs_ids = spec.options.get("vector_store_ids")
if not vs_ids or not isinstance(vs_ids, list) or not vs_ids[0]:
    raise ValueError("file_search requires options['vector_store_ids'] as a non-empty list of store ids.")
# all good -> build the tool

def is_valid_vector_store_ids(v) -> bool:
    return isinstance(v, list) and len(v) > 0 and all(isinstance(i, str) and i for i in v)

When it happens

Trigger: Defining a declarative tool of type 'file_search' where options.vector_store_ids is missing, is not a list, or is an empty/None-first-element list (e.g. {'vector_store_ids': [None]} or {'vector_store_ids': []}).

Common situations: Forgetting to create the vector store first and capture its id; passing a single string instead of a list; referencing a variable that is None at spec-build time; typos like 'vectorStoreIds'.

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}
• Missing 'type' field in agent definition.
• Kernel instance is required for tool resolution.
• Tool id '{tool_id}' must be in format PluginName.FunctionNam

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