test(neo4j): add integration tests and docs for vector search (googleapis#2902)

Author: duwenxin99

.ci/integration.cloudbuild.yaml

@@ -536,7 +536,7 @@ steps:
       - "GOPATH=/gopath"
       - "NEO4J_DATABASE=$_NEO4J_DATABASE"
       - "NEO4J_URI=$_NEO4J_URI"
-    secretEnv: ["NEO4J_USER", "NEO4J_PASS"]
+    secretEnv: ["NEO4J_USER", "NEO4J_PASS", "API_KEY"]
     volumes:
       - name: "go"
         path: "/gopath"

docs/en/integrations/neo4j/tools/neo4j-cypher.md

@@ -67,6 +67,71 @@ parameters:
     description: 4 digit number starting in 1900 up to the current year
 ```
 
+### Vector Search
+
+Neo4j supports vector similarity search. When using an `embeddingModel` with a `neo4j-cypher` tool, the tool automatically converts text parameters into the vector format required by Neo4j.
+
+#### Define the Embedding Model
+
+See [EmbeddingModels](../../../documentation/configuration/embedding-models/_index.md) for more information.
+
+kind: embeddingModel
+name: gemini-model
+type: gemini
+model: gemini-embedding-001
+apiKey: ${GOOGLE_API_KEY}
+dimension: 768
+
+#### Vector Ingestion Tool
+
+This tool stores both the raw text and its vector representation. It uses `valueFromParam` to hide the vector conversion logic from the LLM, ensuring the Agent only has to provide the content once.
+```yaml
+kind: tool
+name: insert_doc_neo4j
+type: neo4j-cypher
+source: my-neo4j-source
+statement: |
+  CREATE (n:Document {content: $content, embedding: $text_to_embed})
+  RETURN 1 as result
+description: |
+  Index new documents for semantic search in Neo4j.
+parameters:
+  - name: content
+    type: string
+    description: The text content to store.
+  - name: text_to_embed
+    type: string
+    # Automatically copies 'content' and converts it to a vector array
+    valueFromParam: content
+    embeddedBy: gemini-model
+```
+
+#### Vector Search Tool
+
+This tool allows the Agent to perform a natural language search. The query string provided by the Agent is converted into a vector before the Cypher statement is executed.
+
+```yaml
+kind: tool
+name: search_docs_neo4j
+type: neo4j-cypher
+source: my-neo4j-source
+statement: |
+  MATCH (n:Document)
+  WITH n, vector.similarity.cosine(n.embedding, $query) AS score
+  WHERE score IS NOT NULL
+  ORDER BY score DESC
+  LIMIT 1
+  RETURN n.content as content
+description: |
+  Search for documents in Neo4j using natural language. 
+  Returns the most semantically similar result.
+parameters:
+  - name: query
+    type: string
+    description: The search query to be converted to a vector.
+    embeddedBy: gemini-model
+```
+
 ## Reference
 
 | **field**   |                **type**                 | **required** | **description**                                                                              |

tests/neo4j/neo4j_integration_test.go

@@ -77,44 +77,56 @@ func TestNeo4jToolEndpoints(t *testing.T) {
 	// This configuration defines the data source and the tools to be tested.
 	toolsFile := map[string]any{
 		"sources": map[string]any{
-			"my-neo4j-instance": sourceConfig,
+			"my-instance": sourceConfig,
 		},
 		"tools": map[string]any{
 			"my-simple-cypher-tool": map[string]any{
 				"type":        "neo4j-cypher",
-				"source":      "my-neo4j-instance",
+				"source":      "my-instance",
 				"description": "Simple tool to test end to end functionality.",
 				"statement":   "RETURN 1 as a;",
 			},
 			"my-simple-execute-cypher-tool": map[string]any{
 				"type":        "neo4j-execute-cypher",
-				"source":      "my-neo4j-instance",
+				"source":      "my-instance",
 				"description": "Simple tool to test end to end functionality.",
 			},
 			"my-readonly-execute-cypher-tool": map[string]any{
 				"type":        "neo4j-execute-cypher",
-				"source":      "my-neo4j-instance",
+				"source":      "my-instance",
 				"description": "A readonly cypher execution tool.",
 				"readOnly":    true,
 			},
 			"my-schema-tool": map[string]any{
 				"type":        "neo4j-schema",
-				"source":      "my-neo4j-instance",
+				"source":      "my-instance",
 				"description": "A tool to get the Neo4j schema.",
 			},
 			"my-schema-tool-with-cache": map[string]any{
 				"type":               "neo4j-schema",
-				"source":             "my-neo4j-instance",
+				"source":             "my-instance",
 				"description":        "A schema tool with a custom cache expiration.",
 				"cacheExpireMinutes": 10,
 			},
 			"my-populated-schema-tool": map[string]any{
 				"type":        "neo4j-schema",
-				"source":      "my-neo4j-instance",
+				"source":      "my-instance",
 				"description": "A tool to get the Neo4j schema from a populated DB.",
 			},
 		},
 	}
+
+	insertStmt := `CREATE (n:SenseAIDocument {content: $content, embedding: $text_to_embed}) RETURN 1 as result`
+	searchStmt := `
+        MATCH (n:SenseAIDocument)
+        WITH n, vector.similarity.cosine(n.embedding, $query) AS score
+        WHERE score IS NOT NULL
+        ORDER BY score DESC
+        LIMIT 1
+        RETURN n.content as content
+    `
+	toolsFile = tests.AddSemanticSearchConfig(t, toolsFile, "neo4j-cypher", insertStmt, searchStmt)
+
 	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
 	if err != nil {
 		t.Fatalf("command initialization returned an error: %s", err)
@@ -578,4 +590,9 @@ func TestNeo4jToolEndpoints(t *testing.T) {
 			}
 		})
 	}
+
+	// Semantic search tests
+	semanticInsertWant := `[{"result":1}]`
+	semanticSearchWant := `[{"content":"The quick brown fox jumps over the lazy dog"}]`
+	tests.RunSemanticSearchToolInvokeTest(t, semanticInsertWant, semanticInsertWant, semanticSearchWant)
 }