weiqingy opened a new issue, #958:
URL: https://github.com/apache/flink-agents/issues/958
### Background
`clazz:` values in a YAML agent definition are resolved through three
hand-maintained copies of the same alias table, with nothing cross-checking
them:
- Java:
`api/src/main/java/org/apache/flink/agents/api/yaml/Aliases.java:82-142`
- Python: `python/flink_agents/api/yaml/aliases.py`
- Docs: `docs/content/docs/development/yaml.md:522-551`
Adding an integration and adding its alias are separate steps, and nothing
fails when the second one is skipped. Both loaders pass an unrecognized name
through unchanged, so the class stays reachable by fully-qualified name and no
test notices. Java, `Aliases.java:183-187`:
```java
Map<String, String> bucket = byLang.get(language);
if (bucket == null) {
return name;
}
return bucket.getOrDefault(name, name);
```
Python, `aliases.py`:
```python
bucket = CLAZZ_ALIASES.get(resource_type, {}).get(language, {})
return bucket.get(name, name)
```
`yaml.md:554` documents that pass-through as intended user-facing behavior,
which is reasonable on its own but also means an omitted alias is invisible.
This has been caught after the fact before. #812 was a whole PR whose only
substance was adding Bedrock's aliases to all three tables, well after the
Bedrock integration itself shipped.
Comparing `ResourceName.java` against the alias tables at `main` turns up
two problems.
### 1. Six implementations exist with a `ResourceName` constant and no alias
All six classes exist at `main`; only the alias entry is missing.
| Resource type | Implementation | Constant | In alias tables |
|---|---|---|---|
| `chat_model_connections` / `chat_model_setups` (java) | Gemini |
`ResourceName.java:69-72` | no |
| `chat_model_connections` / `chat_model_setups` (java) | Azure OpenAI |
`ResourceName.java:93-96` | no |
| `vector_stores` (java) | OpenSearch | `ResourceName.java:199-200` | no |
| `vector_stores` (java) | S3 Vectors | `ResourceName.java:203-204` | no |
| `vector_stores` (java) | Milvus | `ResourceName.java:207-208` | no |
| `vector_stores` (python) | Mem0 | `ResourceName.java:225-226` | no |
The vector-store table is the thinnest. `Aliases.java:137-142` registers
exactly one alias per language:
```java
// VECTOR_STORE
Map<String, String> vsJava = new HashMap<>();
vsJava.put("elasticsearch",
ResourceName.VectorStore.ELASTICSEARCH_VECTOR_STORE);
Map<String, String> vsPython = new HashMap<>();
vsPython.put("chroma", ResourceName.VectorStore.Python.CHROMA_VECTOR_STORE);
```
while `ResourceName.VectorStore` declares four Java implementations and two
Python ones.
`grep -niE "gemini|milvus|opensearch|s3" ` returns zero matches in both
`Aliases.java` and `aliases.py`.
### 2. The `azure` alias resolves to a different provider than the docs claim
`yaml.md:532` tells the user:
| Alias | `type: python` | `type: java` |
| --- | --- | --- |
| `azure` | — | Azure OpenAI (Java) |
The code maps it elsewhere. `Aliases.java:89`:
```java
chatConnJava.put("azure", ResourceName.ChatModel.AZURE_CONNECTION);
```
and `AZURE_CONNECTION` is the Azure AI Inference connection, not the Azure
OpenAI one (`ResourceName.java:57-58`):
```java
public static final String AZURE_CONNECTION =
"org.apache.flink.agents.integrations.chatmodels.azureai.AzureAIChatModelConnection";
```
Those are two different integrations against two different services.
`AzureAIChatModelConnection` builds on `com.azure.ai.inference`, while
`AzureOpenAIChatModelConnection` lives in the `openai` package and targets
Azure OpenAI.
So a user who follows the doc and writes `clazz: azure` expecting Azure
OpenAI gets the Azure AI Inference connection instead, and the actual Azure
OpenAI Java connection has no alias to reach it by. This is worth resolving
sooner than the rest, because the SDK behind the class `azure` currently
resolves to is the subject of #931 and retires on 2026-08-26.
The Python side is consistent here: `azure_openai` maps to the Python Azure
OpenAI connection in both the code and the doc table.
### Proposed handling
Item 2 is a correctness fix and small: decide what `azure` should mean, add
an alias for the Azure OpenAI Java connection, and make `yaml.md` match the
code. Item 1 is mechanical: add the six entries across the three tables,
following the shape #812 used.
I'd suggest doing item 2 first and on its own, since it changes the meaning
of an alias users may already have in their YAML and deserves its own
discussion, while item 1 is purely additive.
One open question on item 1 worth settling in the same place: should any of
these six be deliberately unaliased? A few are thin wrappers or have external
service requirements, so if the intent is that only first-class integrations
get a short alias, that is a fine answer and worth writing down in `yaml.md` so
the next contributor knows the rule.
I'm willing to submit PRs for both.
--
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]
