Python: Add core vector store abstractions

.github/CODEOWNERS

@@ -61,6 +61,7 @@
 /python/packages/claude/                                        @chetantoshniwal @eavanvalkenburg @giles17 @moonbox3
 /python/packages/copilotstudio/                                 @chetantoshniwal @eavanvalkenburg @giles17 @moonbox3
 /python/packages/core/                                          @chetantoshniwal @eavanvalkenburg @moonbox3 @TaoChenOSU @jpalvarezl @giles17
+/python/packages/core/agent_framework/_vectors.py               @chetantoshniwal @westey-m @eavanvalkenburg @giles17 @moonbox3 @TaoChenOSU @jpalvarezl @peibekwe @baywet @rogerbarreto @SergeyMenshykh
 /python/packages/core/agent_framework/_workflows/               @chetantoshniwal @eavanvalkenburg @moonbox3 @TaoChenOSU @jpalvarezl
 /python/packages/core/agent_framework/_harness/                 @chetantoshniwal @westey-m @eavanvalkenburg @moonbox3
 /python/packages/declarative/                                   @chetantoshniwal @eavanvalkenburg @moonbox3 @peibekwe @baywet

docs/specs/feature-usage-bit-registry.md

@@ -137,7 +137,8 @@ only to approved first-party endpoints.
 | 16 | `core.mcp_skills_source` | MCP-backed skills | `agent_framework.MCPSkillsSource` |
 | 17 | `core.session_store` | Agent session store | `agent_framework.SessionStore` / `FileSessionStore` |
 | 18 | `core.agent_hooks` | Agent Hooks middleware | `agent_framework.create_agent_hooks_middleware` |
-| 19–31 | _reserved_ | core growth | — |
+| 19 | `core.vector_stores` | Vector store abstractions | `BaseVectorCollection` / `BaseVectorSearch` operations |
+| 20–31 | _reserved_ | core growth | — |
 | 32 | `orchestration.sequential` | Sequential orchestration | `agent_framework_orchestrations.SequentialBuilder` |
 | 33 | `orchestration.concurrent` | Concurrent orchestration | `agent_framework_orchestrations.ConcurrentBuilder` |
 | 34 | `orchestration.group_chat` | Group-chat orchestration | `agent_framework_orchestrations.GroupChatBuilder` |

python/packages/core/AGENTS.md

@@ -13,6 +13,7 @@ agent_framework/
 ├── _clients.py          # Chat client base classes and protocols
 ├── _types.py            # Core types (Message, ChatResponse, Content, etc.)
 ├── _tools.py            # Tool definitions and function invocation
+├── _vectors.py          # Vector store models, CRUD/search abstractions, and protocols
 ├── _middleware.py       # Middleware system for request/response interception
 ├── _sessions.py         # AgentSession and context provider abstractions
 ├── _skills.py           # Agent Skills system (models, executors, provider)
@@ -64,6 +65,19 @@ agent_framework/
 - **`@tool`** decorator - Converts functions to tools
 - **`use_function_invocation()`** - Decorator to add automatic function calling to chat clients
 
+### Vector stores (`_vectors.py`)
+
+The vector store API is experimental under the shared `VECTOR_STORES` feature ID.
+
+- **`@vectorstoremodel`** - Declares key, data, and vector fields on dataclasses, Pydantic models, and plain classes
+- **`register_vectorstoremodel`** - Registers one definition and msgspec-backed codec pair per model type
+- **`BaseVectorCollection`** - Base class for collection lifecycle and msgspec-backed record CRUD operations;
+  upserts generate embeddings by default and retrieval excludes vectors by default
+- **`BaseVectorStore`** - Base class for stores that create collection clients
+- **`BaseVectorSearch`** - Base class for vector and keyword-hybrid search
+- **`create_vector_search_tool`** - Creates an agent tool from any `SupportsVectorSearch` implementation
+- **`SupportsVectorUpsert`** / **`SupportsVectorSearch`** - Structural protocols for vector store capabilities
+
 ### Middleware (`_middleware.py`)
 
 - **`AgentMiddleware`** - Intercepts agent `run()` calls

python/packages/core/agent_framework/__init__.py

@@ -284,6 +284,25 @@
         "validate_tool_mode",
         "validate_tools",
     ),
+    "._vectors": (
+        "DISTANCE_FUNCTION_DIRECTION_HELPER",
+        "BaseVectorCollection",
+        "BaseVectorSearch",
+        "BaseVectorStore",
+        "DistanceFunction",
+        "FieldTypes",
+        "IndexKind",
+        "SearchResponse",
+        "SearchResults",
+        "SearchType",
+        "SupportsVectorSearch",
+        "SupportsVectorUpsert",
+        "VectorStoreCollectionDefinition",
+        "VectorStoreField",
+        "create_vector_search_tool",
+        "register_vectorstoremodel",
+        "vectorstoremodel",
+    ),
     "._workflows._agent": ("WorkflowAgent",),
     "._workflows._agent_executor": ("AgentExecutor", "AgentExecutorRequest", "AgentExecutorResponse"),
     "._workflows._agent_utils": ("resolve_agent_id",),
@@ -371,6 +390,7 @@
     "DEFAULT_MODE_SOURCE_ID",
     "DEFAULT_TODO_SOURCE_ID",
     "DEFAULT_TOOL_APPROVAL_SOURCE_ID",
+    "DISTANCE_FUNCTION_DIRECTION_HELPER",
     "EXCLUDED_KEY",
     "EXCLUDE_REASON_KEY",
     "GROUP_ANNOTATION_KEY",
@@ -412,6 +432,9 @@
     "BaseAgent",
     "BaseChatClient",
     "BaseEmbeddingClient",
+    "BaseVectorCollection",
+    "BaseVectorSearch",
+    "BaseVectorStore",
     "CachingSkillsSource",
     "Case",
     "CharacterEstimatorTokenizer",
@@ -438,6 +461,7 @@
     "DeduplicatingSkillsSource",
     "Default",
     "DelegatingSkillsSource",
+    "DistanceFunction",
     "Edge",
     "EdgeCondition",
     "EdgeDuplicationError",
@@ -456,6 +480,7 @@
     "ExperimentalFeature",
     "FanInEdgeGroup",
     "FanOutEdgeGroup",
+    "FieldTypes",
     "FileAccessProvider",
     "FileCheckpointStorage",
     "FileHistoryProvider",
@@ -490,6 +515,7 @@
     "InMemoryHistoryProvider",
     "InMemorySkillsSource",
     "InProcRunnerContext",
+    "IndexKind",
     "InlineSkill",
     "InlineSkillResource",
     "InlineSkillScript",
@@ -527,6 +553,9 @@
     "Runner",
     "RunnerContext",
     "SamplingApprovalCallback",
+    "SearchResponse",
+    "SearchResults",
+    "SearchType",
     "SecretString",
     "SelectiveToolCallCompactionStrategy",
     "ServiceSessionId",
@@ -555,6 +584,8 @@
     "SupportsImageGenerationTool",
     "SupportsMCPTool",
     "SupportsShellTool",
+    "SupportsVectorSearch",
+    "SupportsVectorUpsert",
     "SupportsWebSearchTool",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
@@ -580,6 +611,8 @@
     "UsageDetails",
     "UserInputRequiredException",
     "ValidationTypeEnum",
+    "VectorStoreCollectionDefinition",
+    "VectorStoreField",
     "Workflow",
     "WorkflowAgent",
     "WorkflowBuilder",
@@ -613,6 +646,7 @@
     "create_always_approve_tool_with_arguments_response",
     "create_edge_runner",
     "create_harness_agent",
+    "create_vector_search_tool",
     "detect_media_type_from_base64",
     "enqueue_messages",
     "evaluate_agent",
@@ -636,6 +670,7 @@
     "prepend_instructions_to_messages",
     "register_checkpoint_type",
     "register_state_type",
+    "register_vectorstoremodel",
     "resolve_agent_id",
     "response_handler",
     "set_agent_mode",
@@ -650,6 +685,7 @@
     "validate_tool_mode",
     "validate_tools",
     "validate_workflow_graph",
+    "vectorstoremodel",
     "workflow",
 ]
 

python/packages/core/agent_framework/__init__.pyi

@@ -250,6 +250,25 @@ from ._types import (
     validate_tool_mode,
     validate_tools,
 )
+from ._vectors import (
+    DISTANCE_FUNCTION_DIRECTION_HELPER,
+    BaseVectorCollection,
+    BaseVectorSearch,
+    BaseVectorStore,
+    DistanceFunction,
+    FieldTypes,
+    IndexKind,
+    SearchResponse,
+    SearchResults,
+    SearchType,
+    SupportsVectorSearch,
+    SupportsVectorUpsert,
+    VectorStoreCollectionDefinition,
+    VectorStoreField,
+    create_vector_search_tool,
+    register_vectorstoremodel,
+    vectorstoremodel,
+)
 from ._workflows._agent import WorkflowAgent
 from ._workflows._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
 from ._workflows._agent_utils import resolve_agent_id
@@ -335,6 +354,7 @@ __all__ = [
     "DEFAULT_MODE_SOURCE_ID",
     "DEFAULT_TODO_SOURCE_ID",
     "DEFAULT_TOOL_APPROVAL_SOURCE_ID",
+    "DISTANCE_FUNCTION_DIRECTION_HELPER",
     "EXCLUDED_KEY",
     "EXCLUDE_REASON_KEY",
     "GROUP_ANNOTATION_KEY",
@@ -376,6 +396,9 @@ __all__ = [
     "BaseAgent",
     "BaseChatClient",
     "BaseEmbeddingClient",
+    "BaseVectorCollection",
+    "BaseVectorSearch",
+    "BaseVectorStore",
     "CachingSkillsSource",
     "Case",
     "CharacterEstimatorTokenizer",
@@ -402,6 +425,7 @@ __all__ = [
     "DeduplicatingSkillsSource",
     "Default",
     "DelegatingSkillsSource",
+    "DistanceFunction",
     "Edge",
     "EdgeCondition",
     "EdgeDuplicationError",
@@ -420,6 +444,7 @@ __all__ = [
     "ExperimentalFeature",
     "FanInEdgeGroup",
     "FanOutEdgeGroup",
+    "FieldTypes",
     "FileAccessProvider",
     "FileCheckpointStorage",
     "FileHistoryProvider",
@@ -454,6 +479,7 @@ __all__ = [
     "InMemoryHistoryProvider",
     "InMemorySkillsSource",
     "InProcRunnerContext",
+    "IndexKind",
     "InlineSkill",
     "InlineSkillResource",
     "InlineSkillScript",
@@ -491,6 +517,9 @@ __all__ = [
     "Runner",
     "RunnerContext",
     "SamplingApprovalCallback",
+    "SearchResponse",
+    "SearchResults",
+    "SearchType",
     "SecretString",
     "SelectiveToolCallCompactionStrategy",
     "ServiceSessionId",
@@ -519,6 +548,8 @@ __all__ = [
     "SupportsImageGenerationTool",
     "SupportsMCPTool",
     "SupportsShellTool",
+    "SupportsVectorSearch",
+    "SupportsVectorUpsert",
     "SupportsWebSearchTool",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
@@ -544,6 +575,8 @@ __all__ = [
     "UsageDetails",
     "UserInputRequiredException",
     "ValidationTypeEnum",
+    "VectorStoreCollectionDefinition",
+    "VectorStoreField",
     "Workflow",
     "WorkflowAgent",
     "WorkflowBuilder",
@@ -577,6 +610,7 @@ __all__ = [
     "create_always_approve_tool_with_arguments_response",
     "create_edge_runner",
     "create_harness_agent",
+    "create_vector_search_tool",
     "detect_media_type_from_base64",
     "enqueue_messages",
     "evaluate_agent",
@@ -600,6 +634,7 @@ __all__ = [
     "prepend_instructions_to_messages",
     "register_checkpoint_type",
     "register_state_type",
+    "register_vectorstoremodel",
     "resolve_agent_id",
     "response_handler",
     "set_agent_mode",
@@ -614,5 +649,6 @@ __all__ = [
     "validate_tool_mode",
     "validate_tools",
     "validate_workflow_graph",
+    "vectorstoremodel",
     "workflow",
 ]

python/packages/core/agent_framework/_feature_stage.py

@@ -64,6 +64,7 @@ class ExperimentalFeature(str, Enum):
     PROGRESSIVE_TOOLS = "PROGRESSIVE_TOOLS"
     SESSION_STORE = "SESSION_STORE"
     TO_PROMPT_AGENT = "TO_PROMPT_AGENT"
+    VECTOR_STORES = "VECTOR_STORES"
 
 
 class ReleaseCandidateFeature(str, Enum):

python/packages/core/agent_framework/_telemetry.py

@@ -55,6 +55,7 @@ class FeatureIndex(IntEnum):
     CORE_MCP_SKILLS_SOURCE = 16
     CORE_SESSION_STORE = 17
     CORE_AGENT_HOOKS = 18
+    CORE_VECTOR_STORES = 19
 
 
 # This environment variable is reserved by the Foundry hosting environment to