ChickenBenny opened a new pull request, #1400:
URL: https://github.com/apache/flink-agents/pull/1400

   Linked issue: #144
   
   ### Purpose of change
   
   Java agents can now use a declared vector store as a tool, just like Python 
agents. The model decides whether to search, what to search for, and whether to 
try again with a different query.
   
   You build it with `VectorStoreSearchTool.builder()` (`name`, `description`, 
`vectorStore`, optional `maxResults`) and register it like any other tool. To 
make that work, a Java resource registered as an instance now gets the 
`ResourceContext`, which Python already gives it.
   
   #### Runtime flow
   
   1. You register the tool with `addResource` or as an `@Tool` field. Either 
way it goes through `JavaSerializableResourceProvider`, which keeps it as JSON 
in the plan.
   2. The first time the resource cache resolves the tool, the provider 
deserializes it and now also binds the cache's `ResourceContext`. The cache 
then calls `open()`, which looks up `vectorStore` by name and holds on to it.
   3. When the model calls the tool, `call()` runs `VectorStoreQuery(query, 
maxResults)` on that store. It returns a JSON list of `{"content", 
"metadata"}`, or `No relevant documents found.` when nothing matches.
   
   #### Key decisions
   
   - **It's an instance, not a `ResourceDescriptor`.** Tools are instances in 
both languages, so the Java tool has the same shape as the Python one.
   - **The provider binds the context through a new 
`SerializableResource.setResourceContext`.** Without a context, a resource 
registered as an instance can't look up other resources. I put the setter on 
`SerializableResource` instead of `Resource`, because descriptor-created 
resources already get the context in their constructor. Python binds the 
context only when it deserializes the resource, while Java binds it on every 
`provide()`. On an operator the resource is always deserialized, so they end up 
the same. Each provider only serves one cache (the operator and each internal 
sub-agent decode their own from plan JSON), so nothing overwrites the context.
   - **The store is resolved in `open()`.** `call()` can run in parallel async 
workers, and the resource cache isn't thread-safe. Same as Python.
   - **Errors are thrown, not returned as `ToolResponse.error`.** Same as 
Python. The `UncapturableException` guard lives in `plan`, so `api` can't use 
it.
   - **Metadata goes through a lightly configured `ObjectMapper`.** Three lines 
of config make it write `java.time` and `Date` as ISO-8601 strings and 
property-less objects as `{}`. So the response is always valid JSON, which is 
what Python's `_to_json_compatible` guarantees too. I didn't reuse 
`ToolResultUtils.toToolResponse` for two reasons: it's in `plan`, which `api` 
can't depend on, and when serialization fails it falls back to 
`String.valueOf`, so the model would get a Java `toString()` instead of JSON.
   
   ### Behavioral Semantics
   
   #### Interaction decisions
   
   For the Java tool, by vector store language and `tool-call.async` (the 
Python tool doesn't change):
   
   | Vector store | `tool-call.async` | Flink 1.20.4 and earlier, 2.0.0–2.0.1, 
2.1.0–2.1.2, 2.2.0 | Other Flink versions |
   |---|---|---|---|
   | Java | any | works | works |
   | Python | `false` | works (not tested) | works (not tested) |
   | Python | `true` | not supported; the docs say to set it to `false` | works 
(not tested) |
   
   `ContextRetrievalAction` falls back to sync for a Python store by itself. 
The tool can't, because it lives in `api` and can't call `Utils.supportAsync()`.
   
   #### Behavioral contracts
   
   1. The model sees one required string argument, `query`.
   2. The query is sent as `queryText` with `limit = maxResults` (default 3).
   3. The vector store is looked up by name once, in `open()`, and every call 
reuses it.
   4. Each result has exactly `content` and `metadata`, in the order the store 
returns them.
   5. When nothing matches, the tool returns `No relevant documents found.`.
   6. The response is always valid JSON, even with `java.time`, `Date`, 
`byte[]`, NaN or property-less metadata values.
   7. Errors from the vector store propagate out of `call()`.
   8. `build()` requires `name`, `description` and `vectorStore`, and a 
positive `maxResults`.
   9. Settings survive the agent plan JSON round trip, whether the tool is an 
`@Tool` field or added with `addResource`.
   10. A Java serializable resource gets the cache's `ResourceContext` from 
`provide()`, before `open()`.
   
   #### Failure behavior
   
   | Failure | What happens |
   |---|---|
   | Missing `name`, `description` or `vectorStore`; `maxResults` ≤ 0 | 
`NullPointerException` / `IllegalArgumentException` from `build()` |
   | `vectorStore` isn't declared, or isn't a vector store | thrown from 
`open()` when the tool is first resolved; the tool isn't cached |
   | `query` missing or not a string; called before `open()` | 
`IllegalArgumentException` / `IllegalStateException` at call time |
   | The embedding model or vector store fails during a search | thrown at call 
time; `ToolCallAction` records it as a tool error |
   
   ### Tests
   
   | Contract | Tests |
   |---|---|
   | 1 | `metadataExposesOnlyQueryArgument` |
   | 2 | `callQueriesWithQueryTextAndMaxResults`, `maxResultsDefaultsToThree` |
   | 3 | `openResolvesVectorStoreOnceByName`, `callBeforeOpenThrows`, 
`concurrentCallsShareTheStoreOpenedOnceWithTheTool` |
   | 4 | `callReturnsContentAndMetadataOnly` |
   | 5 | `callReturnsMessageWhenNothingMatches` |
   | 6 | `callWritesUnusualMetadataAsValidJson` |
   | 7 | `callPropagatesVectorStoreErrors` |
   | 8 | `rejectsInvalidArguments`, `callRejectsMissingOrNonStringQuery` |
   | 9 | `survivesJsonRoundTrip`, 
`annotatedFieldToolSurvivesPlanJsonAndResolvesItsStore`, 
`programmaticToolSurvivesPlanJsonAndResolvesItsStore` |
   | 10 | `provideBindsResourceContextToRegisteredInstance`, 
`provideBindsResourceContextToDeserializedInstance` |
   
   The api tests mock the context and the store, and the plan tests go through 
`AgentPlan` JSON. The riskiest part is the runtime path, so 
`VectorStoreSearchToolResourceCacheTest` resolves the tool through a real 
`ResourceCache` from a deserialized provider. It runs two overlapping calls and 
checks that the store is provided, opened and closed exactly once, and it also 
covers an undeclared store. Both tests fail if the provider doesn't bind the 
context.
   
   Passed on JDK 11: the full `api` (895 run, 16 skipped) and `plan` (748 run, 
5 skipped) suites, the runtime tests above plus `ResourceCacheTest`, and 
Spotless.
   
   **Not verified**
   - A real Java vector store behind the tool, with a live model calling it.
   - A Java tool with a Python vector store, with either `tool-call.async` 
setting.
   - How the docs render in Hugo.
   - The full `./tools/ut.sh` run.
   
   <details>
   <summary>Implementation invariants and test commands</summary>
   
   - The tool's plan JSON has exactly `metadata`, `vectorStore` and 
`maxResults`. `@JsonIgnoreProperties` drops `resourceContext` and `toolType`, 
and the resolved store is a `@JsonIgnore transient` field.
   - The resolved store is `volatile`: `open()` writes it on the mailbox thread 
and async workers read it.
   - `SerializableResource.setResourceContext` has no Jackson annotation, so 
the plan JSON of existing serializable resources doesn't change. Resources are 
serialized only when the provider is created, before any context is bound.
   - `getToolType()` returns `FUNCTION`, like Python.
   - The input schema is a string constant, like `BashTool` and `LoadSkillTool`.
   - Metadata the configured mapper still can't write (a cycle, a throwing 
getter) raises `IllegalStateException` at call time. Built-in stores can't 
produce that.
   
   ```bash
   mvn -B -pl runtime -am test \
     
-Dtest='VectorStoreSearchToolTest,AgentPlanVectorStoreSearchToolTest,JavaSerializableResourceProviderTest,VectorStoreSearchToolResourceCacheTest,ResourceCacheTest'
 \
     -Dsurefire.failIfNoSpecifiedTests=false
   mvn -B -pl plan -am test
   ```
   
   </details>
   
   ### API
   
   Adds `org.apache.flink.agents.api.tools.VectorStoreSearchTool` with its 
`Builder`, plus a public 
`SerializableResource.setResourceContext(ResourceContext)` that the framework 
calls. `Resource` only gets a Javadoc fix.
   
   What changes for existing code: serializable resources (prompts, function 
tools, skills, custom tools) now get the cache's context from 
`getResourceContext()` instead of `null`. Their plan JSON and behavior stay the 
same. Descriptor-created resources don't change and don't get the setter. YAML 
can't declare the tool yet; that can come in a follow-up for both languages.
   
   ### Documentation
   
   - [ ] `doc-needed`
   - [ ] `doc-not-needed`
   - [x] `doc-included`
   
   The "Use as a Tool" section of the vector stores page gets a Java tab, 
including the `@Tool` field form, where the field name has to match 
`.name(...)`. The hint now also covers a tool and a store in different 
languages.
   
   ### Was this patch authored or co-authored using generative AI tooling?
   
   - [x] Yes
   - [ ] No
   
   Generated-by: Claude Code 2.1.326 (Claude Opus 5.5)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to