joeyutong commented on code in PR #918: URL: https://github.com/apache/flink-agents/pull/918#discussion_r3644665749
########## dev/agent-skills/flink-agents-dev/references/yaml-patterns.md: ########## @@ -0,0 +1,276 @@ +# YAML Patterns + +## Contents + +- [Contract First](#contract-first) +- [Canonical Workflow Shape](#canonical-workflow-shape) +- [Section Rules](#section-rules) +- [Language Selection](#language-selection) +- [Name-resolution Pass](#name-resolution-pass) + +## Contract First + +Use the [bundled YAML schema](../assets/yaml-schema.json) as the offline contract +before generating YAML. If the target application provides a schema for its pinned +Flink Agents version, use that matching schema instead. The schema defines structure; +target-version provider metadata defines the additional arguments forwarded by +Resource descriptors. + +The valid top-level sections are: + +```text +agents, actions, chat_model_connections, chat_model_setups, +embedding_model_connections, embedding_model_setups, prompts, tools, +skills, vector_stores, mcp_servers +``` + +Top-level Resources and Actions are shared. The same sections nested under an +`agents[]` entry belong to that Agent. There is no `resources:` wrapper and no Agent +`type` field. + +## Canonical Workflow Shape + +This example deliberately shows only the Action structure. It contains no model, +Prompt, Tool, Skill, MCP server, or vector store because those Resources must come +from the staged user interview. Generate `app.actions` with matching skeletons; do +not infer what either Action emits. + +```yaml +agents: + - name: application_agent + + actions: + - name: process_input + function: app.actions:process_input + trigger_conditions: [input] Review Comment: **Case 013 — selected-version contract.** The input selected Flink Agents 0.3.0, Flink 2.0.2, YAML, and Python, with the release-0.3.0 source and schema available. The expected behavior was to bind the generated YAML to that selected release. Instead, the result used `trigger_conditions` from this bundled/current example, while release-0.3.0 requires `listen_to`. Since the latest source uses `trigger_conditions`, I do not think this review should prescribe one field as the universal fix. Could you make the support policy explicit and consistent—either make the patterns version-aware when older releases are selectable, or scope the Skill to the current snapshot and stop presenting incompatible historical releases as supported targets? A version offered to the user should not produce artifacts using another version's YAML contract. ########## dev/agent-skills/flink-agents-dev/SKILL.md: ########## @@ -0,0 +1,321 @@ +--- +name: flink-agents-dev +description: Use when building, scaffolding, modifying, debugging, converting, or verifying Apache Flink Agents applications, including Flink Agents YAML, Workflow Agent, ReAct Agent, Actions, Resources, MCP servers, vector stores, runtime skills, Python, or Java. +--- + +# Developing Flink Agents Applications + +## Core Model + +Model every application as four connected parts: + +1. **Resources**: named models, prompts, tools, skills, vector stores, MCP servers, + and connections. +2. **Actions**: event handlers that use Resources and emit events. +3. **Orchestration**: trigger conditions and emitted-event graph. +4. **Implementation**: Python/Java functions, types, and runner. + +Skills, vector stores, MCP, RAG, and memory are combinations of these parts. + +The Agent API language and custom Action/Tool language do not constrain every +Resource implementation. Chat-model connections/setups, embedding-model +connections/setups, and vector stores support Python/Java bridging in both +directions in the bundled snapshot. For those Resource types, offer every +target-version implementation supported natively or through the bridge, regardless +of whether the application uses YAML, direct Python, or direct Java. Treat the +selected implementation's language as part of that Resource choice; do not add a +separate application-wide cross-language confirmation. Do not generalize this rule +to Resource types that lack a verified bridge. + +## Source Authority + +This skill must work from its installed directory; never assume the user cloned the +Flink Agents repository. Resolve bundled paths relative to this `SKILL.md`. + +Inspect the target version and conventions. Use sources in this order: + +1. Target application code, dependency metadata, installed package/JAR APIs, and tests. +2. Version-matching Flink Agents schema, docs, examples, or source when available. +3. This skill's references and [bundled YAML schema](assets/yaml-schema.json) as + the offline baseline. + +The bundled schema and patterns describe the Flink Agents revision that published +this skill. If the target dependency differs, prefer its matching contracts and +state any compatibility assumption that could not be verified. + +Do not invent APIs, versions, or commands from memory. + +Before presenting code as runnable, resolve every nontrivial import, constructor, +method, descriptor argument, and dependency coordinate against those sources. If a +contract cannot be resolved, either use a documented alternative or label the +fragment as pseudocode and state exactly what remains unresolved. Never create an +adapter or wrapper merely to make a speculative API look complete. + +## Definition Strategy + +| Situation | Recommendation | +|---|---| +| New Workflow Agent or rewired event graph | Offer YAML plus Python/Java implementation files | +| Existing YAML application | Preserve and extend YAML | +| Existing programmatic Agent | Preserve its current API unless conversion is requested | +| `ReActAgent`, unsupported YAML surface, or explicit code-only request | Direct Python or Java API | + +For a new application, present YAML, direct Python API, and direct Java API as an +explicit choice after versions are confirmed. A recommendation explains the +tradeoff; it is not permission to select the API for the user. + +YAML does not declare an agent `type`. Do not add `type: workflow` or +`type: react`; `type` selects an implementation language where the schema allows it. + +YAML does not choose the business implementation language either. For a new YAML +application, ask the user to choose Python or Java before generating files. For an +existing application, detect and preserve the language from build metadata, source +files, function references, and explicit YAML `type` fields. Do not default to +Python merely because omitted YAML `type` fields currently resolve to Python. + +Workflow Agents already include built-in chat, tool-call, and context-retrieval +Actions. A model reasoning/tool loop can therefore remain YAML-defined. Choose +`ReActAgent` only when the user explicitly wants that programmatic abstraction, the +existing application already uses it, or a required ReAct-specific surface is not +available through YAML. + +## Scaffolding Boundary + +Complete framework-owned wiring, but do not invent business behavior. Unless the +user explicitly asks for an implementation and supplies its contract, generate only +an importable or compilable signature skeleton for each custom Action, Tool, domain +client, data transformation, and runtime Skill. Preserve user-provided names, +parameters, types, and descriptions. When those details are absent, derive a stable +name from the stated capability and use a minimal neutral signature such as one +opaque string request and string result; mark unresolved input fields and result +types with focused TODOs and fail explicitly with `NotImplementedError` or +`UnsupportedOperationException`. Review Comment: **Case 016 — unresolved business contracts.** The input specified only the high-level flow: retrieve context, invoke a chat model, allow an order-query Tool/runtime Skill, and emit an answer. It did not define the input-to-query mapping, context formatting, chat-message construction, or output contract. The expected result was importable Action skeletons that fail explicitly. Instead, the generated Actions chose those transformations and added tests that asserted the invented behavior. Could we strengthen this boundary with an explicit checklist or equivalent constraint logic? For each custom Action, Tool, or domain client, first classify its business contract as supplied or unresolved using only user requirements, existing code, and tests. If unresolved, allow only a signature, focused TODO, and explicit failure; do not emit events, transform payloads, compose messages, return business data, or add tests that assert those behaviors. The exact mechanism can be left to the contributor, but it should be more operational than the current general “do not invent business behavior” rule. -- 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]
