Developing Flink Agents Applications
Core Model
Model every application as four connected parts:
- Resources: named models, prompts, tools, skills, vector stores, MCP servers,
and connections.
- Actions: event handlers that use Resources and emit events.
- Orchestration: trigger conditions and emitted-event graph.
- 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:
- Target application code, dependency metadata, installed package/JAR APIs, and tests.
- Version-matching Flink Agents schema, docs, examples, or source when available.
- This skill's YAML contract manifest, matching
bundled schema, and references as the offline baseline.
Select contracts by the target Flink Agents version, not by the version that
published this skill. The manifest maps released versions to complete schemas and
marks versions without YAML support. The unversioned
main schema describes only the repository revision that
published this skill. Never validate a released application against that schema
unless the manifest maps the selected version to it.
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. Apply
Provider Contract Triage below to external
descriptor-backed Providers before loading bundled references. This blocked
Provider path is different from an unresolved business contract, which still
receives a user-fillable skeleton.
Preflight
Before loading a platform adapter, asking a decision gate, or generating files:
- Confirm that the target is a Flink Agents application or is being converted into
one. Leave ordinary Flink jobs outside this workflow.
- Inspect the complete user request, existing project, dependency metadata, source,
configuration, and tests. Resolve every framework decision already answered by
that evidence. The latest explicit user choice takes precedence; treat a conflict
with existing project metadata as an intentional requested migration and report
it rather than silently restoring the old value.
- Record each required framework decision as
confirmed or unresolved: Flink
Agents version, Flink version, API, YAML application language when applicable,
each descriptor-backed Resource implementation, and the Python environment when
Python is required.
- Run Provider Contract Triage for every concrete external descriptor-backed
Provider already named by the request or project. When the implementation is an
unresolved gate, run the triage immediately after the user selects it.
- Build the ordered gate list from only the
unresolved decisions. If the list is
empty, skip host detection and interaction adapters and proceed directly to
contract resolution and implementation.
- For YAML, select the exact target-version schema through
yaml-contracts.yaml. Filter the API choices when the
manifest says that the selected version has no YAML API. If a requested YAML
version has no matching schema, stop YAML generation and request the exact
target-version schema or source; never substitute the main schema.
Keep this decision record current after every answer. It prevents repeated
questions and ensures that later references operate only on confirmed versions and
capabilities.
Provider Contract Triage
This is an early-exit pass, not a later Build Workflow step. Run it as soon as a
concrete external descriptor-backed Provider class or alias is confirmed and before
reading any file under references/.
Inspect only evidence that can establish that Provider's contract:
- Explicit user-supplied JARs, packages, source, tests, or documentation.
- The target project's dependency metadata and the exact installed artifact named
by that metadata.
- Version-matching authoritative Provider source or documentation already available
at a known location.
Scope every inspection command to the target application's dependency files,
configuration, source roots, and explicitly named artifacts. Exclude the installed
Skill directory containing this SKILL.md, including project-local .agents/, and
exclude host metadata such as .codex/, .claude/, tool caches, and unrelated home
or package caches. Do not run an unscoped recursive search over . when it would
traverse those paths.
Do not load general application, YAML, language, local-development, or verification
references to compensate for a missing Provider artifact. A general YAML schema can
validate descriptor shape but cannot establish a Provider's dependency coordinate,
constructor, or forwarded mandatory arguments. When the user explicitly states that
no Provider artifact or contract source is available, treat that as evidence; check
the target project metadata for an existing dependency, but do not search unrelated
caches or examples.
The triage must establish the implementation class or alias, dependency coordinate
or package, constructor/factory contract, and every mandatory descriptor argument.
If any element remains unverifiable:
- preserve all working dependency, source, and configuration files;
- stop the dependent integration immediately, before the normal Build Workflow;
- do not generate a descriptor, adapter, wrapper, placeholder dependency, or tests;
- report the exact sources checked, each missing contract element, and the minimum
JAR, package, source, test, or documentation needed to continue.
List a source under checked only when its content was actually inspected during
the triage. Do not claim that a bundled schema, reference, cache, or documentation
was checked merely because SKILL.md names it.
Return that blocked report for a Provider-only request. Continue other work only
when the user explicitly requested an independent change that does not depend on the
blocked Provider. If the complete Provider contract is verified, proceed with the
normal workflow using that evidence.
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, derive the available API choices from the confirmed target
version. Present YAML, direct Python API, and direct Java API when all three are
supported; otherwise omit unsupported surfaces. 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. Before
implementing each custom Action, Tool, domain client, data transformation, Prompt,
or runtime Skill, classify these contract elements from only explicit user
requirements, existing code, and existing tests:
| Contract element |
supplied means |
| Input |
Required fields and their meaning are defined |
| Output |
Result fields or emitted Events are defined |
| Transformation |
Input-to-output or message construction is defined |
| Side effects |
External calls, state changes, and authentication boundary are defined |
| Errors |
Required failure and fallback behavior is defined |
Anything not established by those sources is unresolved; a high-level capability
name is not a supplied contract. When behavior depends on an unresolved element,
generate only an importable or compilable signature skeleton with focused TODOs and
an explicit NotImplementedError or UnsupportedOperationException. Preserve
user-provided names, parameters, types, and descriptions. When those are absent,
derive a stable capability name and use the narrowest framework-compatible
signature; for a function Tool or domain client with no typed contract, use one
opaque string request and string result.
An unresolved skeleton must not emit business Events, transform payloads, compose
Prompt or chat messages, call a backend, return business data, or provide fallback
behavior. Tests may check import/compilation, signature and YAML reference
resolution, and explicit failure, but must not assert business behavior that was
not supplied.
Do not author domain rules, REST endpoints, diagnostic procedures, prompts, data
models, Tool results, runtime Skill instructions, or test doubles from a high-level
application idea. Do not propose a standard REST API, MCP server, or mock backend as
the implementation of a custom Tool. Do not ask the user to lock a business input
identity schema, deployment platform, service API, authentication design, or log/
metric backend merely to scaffold the application. Generate the neutral skeleton
and leave those choices as TODOs for the user. Built-in Flink Agents Actions are
framework behavior and need no generated implementation.
Interaction Discipline
This section is the sole authority for interaction capability detection, fallback
selection, retry behavior, and host-mode handling. Platform adapters only describe
how to encode a question for a tool that this section selected; other references
must point here instead of restating this policy.
Process the unresolved decisions from Preflight as sequential gates. Ask only the
current gate, wait for the answer, update the decision record, and continue. Never
send one proposed baseline that bundles versions, API, implementation language,
runtime version, Resource implementations, business backends, and mock behavior.
Only when at least one unresolved closed gate remains, identify the current host
from explicit system and tool context. Use this table to select the sole candidate
tool and adapter for the gate:
| Host |
Candidate structured tool |
Adapter |
| Codex |
request_user_input |
codex.md |
| Claude Code |
AskUserQuestion |
claude-code.md |
| Gemini CLI |
ask_user communication tool |
gemini-cli.md |
| Qoder |
Explicitly exposed structured single-select tool, if any |
qoder.md |
| Unknown or unsupported |
Explicitly exposed structured single-select tool, if any |
generic.md |
Treat the current tool contract as the only capability signal. When the table's
candidate is exposed and callable, read its adapter to encode one question. An
adapter must not perform capability discovery or select a fallback. If the candidate
is absent, returns an availability error, or cannot represent the complete valid
option set without altering or obscuring it, immediately read
generic.md and use its numbered fallback. Do not
retry the tool, ask the user to change modes, require a slash command or keyboard
shortcut, perform a post-interview handoff, add host metadata, or install host
configuration in the generated application.
Never use an open-ended text question when the valid options are already known.
When a gate has a recommendation, place it first and label it (Recommended), but
do not preselect or continue without the user's answer. The YAML
implementation-language gate intentionally has no recommendation: present Python
and Java as equal peer options with parallel descriptions and no (Recommended)
label.
Use this order:
- If unresolved, ask for the Flink Agents version and wait. Then offer only
compatible Flink versions and wait for the Flink choice. Do not mention
Python/JDK versions, an Agent API, a model provider, or business architecture in
these version questions.
- If unresolved, ask the user to choose among the APIs supported by the confirmed
Flink Agents version. Offer YAML only when its exact contract is available. Wait.
- Only when YAML is selected, ask whether custom Actions, function Tools, and the
Flink entry point use Python or Java. Resource implementations are selected
independently at their own gates. Direct Python or Java API already determines
the application-code choice. Do not recommend, preselect, or imply a preference
for either YAML implementation language. Only now resolve a compatible Python or
JDK version.
- Inventory the Resources required by the user's stated design. Resolve real
descriptor-backed framework integrations one at a time and wait before moving to
the next integration. Assign a deterministic internal name, ask for its
implementation class or documented alias, and stop the interview for that
Resource. Immediately run Provider Contract Triage after the implementation
choice; it verifies the target-version constructor and descriptor. If it passes,
generate every mandatory configuration key as
TODO_REQUIRED_<FIELD> for the
user to fill. Do not ask about another Resource or load general references before
the triage result.
For chat-model connections/setups, embedding-model connections/setups, and vector
stores, do not filter candidates by the Agent API or application-code language.
Present all verified Python and Java implementations, label each candidate's
implementation language when needed for disambiguation, and generate the matching
bridge declaration and runtime dependencies after selection.
Do not ask for model identifiers, endpoints, credential values/mechanisms,
provider options, Skill source paths/URLs/packages, or other Resource arguments.
Custom Actions, function Tools, domain clients, Prompt content, runtime Skill
instructions, business input schemas, and backend platforms are not integration
gates: scaffold them without a business interview. Do not ask the user to name a
single Resource or repeat a generated reference. Ask about naming only when
multiple Resources need semantic disambiguation, an existing external reference
constrains the name, or the user requested a naming convention.
- As soon as the confirmed design first requires a Python runtime, pause before
environment creation or dependency installation. Unless the existing project
already declares its environment unambiguously, inspect compatible local Python
executables/environments and ask whether to reuse one of them or create a
project-local
.venv. Wait for the choice and use the selected interpreter for
every install, import, test, and local run. This conditional gate fires
immediately after the choice that introduces Python; do not delay it until the
end of the Resource interview.
- After every framework decision is confirmed, design the Action graph and generate
the project. Do not add a host-specific handoff.
Do not infer OpenAI, Ollama, any model name, an environment-variable credential,
Skill distribution, MCP, a vector store, or a domain-service protocol. After a
framework implementation is selected, do not run a second configuration interview.
Generate a declaration or builder scaffold that names every verified mandatory
argument and leaves its value explicit for the user. For YAML string fields, use a
clear placeholder such as TODO_REQUIRED_API_KEY; for direct APIs, generate a
compilable factory skeleton that lists the required arguments and fails explicitly
until they are filled. If the user already supplied a value or explicitly requested
plaintext in local YAML, use that instruction; keep supplied secrets out of tracked
files and output. Never claim ${ENV_VAR} is interpolated unless the target loader
or provider actually implements it.
The conditional Python-environment gate is dependency management, not Resource
configuration. It still runs when a selected Resource introduces Python, but it asks
only which concrete compatible Python environment to use, never provider values.
Build Workflow
- Run Preflight, including Provider Contract Triage for every concrete external
Provider already named by the request or project. If a Provider is blocked, issue
its report and stop before reading any bundled reference.
- Read application patterns, then ask only the
ordered unresolved gates. Do not repeat decisions already confirmed by the user
or project.
- When versions are unresolved, complete the version gates in
local development: Flink Agents first, then a
compatible Flink version. Do not generate files or combine later decisions into
these questions.
- Complete the API gate with only APIs supported by the confirmed target version.
For YAML, read YAML patterns, select the exact
schema through yaml-contracts.yaml, and reject
generation when no exact contract is available.
- If YAML was selected, complete the implementation-language gate. Then read
Python patterns or
Java patterns for the application code. When a
bridge-supported Resource uses the other language, also read that language's
cross-language Resource section; selecting that Resource is already explicit
confirmation.
- Inventory each Resource and assign stable names automatically. Ask only which
documented implementation alias/class to use for actual framework integrations.
For bridge-supported types, build this choice from both Python and Java
implementations instead of the application-code language alone. Inspect the
selected implementation through Provider Contract Triage before loading more
references or moving to another integration. When it passes, add its integration
and bridge dependencies and scaffold all mandatory configuration keys without
asking for their values.
Classify every custom Tool/Action/Prompt/runtime-Skill business contract before
generating its skeleton; do not ask the user to choose a domain platform or
complete an unresolved input contract. Generate and record all cross-references
without asking the user to repeat internal identifiers. Never select a provider,
model, endpoint, credential source, business backend, or integration from the
application domain alone.
- When runtime Skills are requested, preserve an explicit source in an existing
application. For a new application, generate a minimal runtime
SKILL.md business
scaffold plus a source-configuration TODO that lists the valid paths, urls,
Python package, and Java classpath forms. Do not ask for loading paths or
distribution, and never inspect, copy, or offer to reuse Skills installed in the
coding-agent host, such as a local flink-diag; coding-agent Skills and Flink
runtime Skills are different artifacts. Read
YAML patterns.
- Draw only framework Action graph edges established by built-in contracts or
supplied business contracts. Where an emitted Event, payload transformation,
branch, output, or error contract is unresolved, generate the Action signature
and explicit failure but do not claim or implement that edge. Do not turn those
TODOs into more gates.
- Use only documented built-in Actions. Generate a resolvable, correctly typed
signature skeleton for every other Action and reference it as
<module-or-class>:<qualname>; leave its business body for the user unless they
explicitly requested implementation.
- Resolve concrete API calls and dependency coordinates from the target-version
artifacts before generating the complete executable project. For Java, generate
a Maven project with
flink-agents-api, flink-agents-plan, flink-agents-runtime, and only the
integrations actually used; declare all Flink Agents and Flink dependencies as
provided. Whenever the design requires Python, generate source and dependency
files, resolve the Python environment choice when not already declared, and
install the resolved Flink Agents, PyFlink, and integration dependencies into the
selected existing environment or project-local .venv. Read
local development. Preserve versions already
selected by the target project; never guess one.
- Connect the Agent to a Flink DataStream or Table through the public factory backed
by
RemoteExecutionEnvironment. Local validation submits that same remote-style
job to a MiniCluster. Never use a local Agents environment, a no-argument factory,
from_list/to_list, or their Java equivalents.
- Run the checks in verification before claiming
the application is valid or runnable.
Required Output
- Complete framework files or edits, including every custom function signature and
a remote-style Flink job entry point.
- A runnable Maven project for Java and, whenever Python is required, pinned Python
dependency input plus the user-selected existing environment or populated
project-local
.venv.
- User-confirmed Flink Agents and Flink versions. Never silently choose the bundled
recommended versions for a new project.
- A user-confirmed API choice from the surfaces supported by the selected Flink
Agents version.
- A user-confirmed Python or Java application-code language for every new YAML
application, reflected consistently in project layout, custom Action/Tool function
references, and the Flink entry point. Do not use it to filter bridge-supported
Resource implementations.
- For applications using runtime Skills, a user-fillable Skill business scaffold
and source-configuration TODO. Preserve existing source configuration, but do not
ask a new-project user to choose distribution or reuse coding-agent host Skills.
- Resource declarations built from user-selected implementation aliases/classes,
including independent Resource implementation language and bridge wiring where
supported, with every verified mandatory provider key present and marked for user
input.
Keep model, endpoint, credential, and optional provider values unresolved instead
of interviewing for them or choosing defaults.
- Deterministic Resource names and references generated by the coding agent. Do not
require the user to name ordinary Connection, Setup, Prompt, Skill container,
VectorStore, or MCP Resource identifiers when there is no ambiguity.
- When the user chooses plaintext credentials for local testing, a loader-compatible
local YAML that is excluded from version control and actually used by the local
run command. Do not replace this explicit choice with programmatic registration.
- Explicit user-fillable business skeletons for custom Actions, Tools, prompts,
runtime Skills, domain clients, secrets, endpoints, and external data, backed by
the supplied/unresolved contract classification. Keep framework wiring and
signatures concrete instead of replacing them with fabricated business
implementation.
- A final consolidated
User must provide list for unresolved business input
fields, platform clients, authentication, queries, response mapping, and domain
behavior. These items must not block project scaffolding or become Agent workflow
decisions unless the user explicitly asks for their implementation.
- Exact commands that match the target repository's build tooling; no guessed
package, Flink, provider, model, or plugin versions.
- Framework snippets whose imports and API calls resolve in the target version.
Business skeletons must import or compile, fail explicitly when invoked, and be
labeled user-fillable rather than runnable behavior.
- For YAML, the selected contract key and exact schema path used for validation.
- Evidence separated into schema, load/compile, tests, and runtime.
- A clear statement for every check that was not run or requires an external service.
Quick Reference
| Task |
Read |
| Present closed choices in the current coding agent |
Interaction Discipline, then its selected platform adapter |
| Select Agent/API shape; design Resources and event graph |
application-patterns.md |
| Author or review YAML; resolve names and functions |
yaml-patterns.md |
| Scaffold runtime Skill business and source TODOs |
runtime Skills |
| Scaffold Python Actions, Tools, types, or runner |
python-patterns.md |
| Scaffold Java Actions, Tools, resources, or runner |
java-patterns.md |
| Select versions, generate dependencies, and submit to MiniCluster |
local-development.md |
| Validate schema, references, imports, compilation, and execution claims |
verification.md |
| Select and validate YAML without a source checkout |
YAML contract manifest |
1---2name: flink-agents-dev3description: 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. Do not use for ordinary Flink jobs that do not use Flink Agents.4metadata:5 source: https://skillmd.com/skills/apache/flink-agents-dev6---78# Developing Flink Agents Applications910## Core Model1112Model every application as four connected parts:13141. **Resources**: named models, prompts, tools, skills, vector stores, MCP servers,15 and connections.162. **Actions**: event handlers that use Resources and emit events.173. **Orchestration**: trigger conditions and emitted-event graph.184. **Implementation**: Python/Java functions, types, and runner.1920Skills, vector stores, MCP, RAG, and memory are combinations of these parts.2122The Agent API language and custom Action/Tool language do not constrain every23Resource implementation. Chat-model connections/setups, embedding-model24connections/setups, and vector stores support Python/Java bridging in both25directions in the bundled snapshot. For those Resource types, offer every26target-version implementation supported natively or through the bridge, regardless27of whether the application uses YAML, direct Python, or direct Java. Treat the28selected implementation's language as part of that Resource choice; do not add a29separate application-wide cross-language confirmation. Do not generalize this rule30to Resource types that lack a verified bridge.3132## Source Authority3334This skill must work from its installed directory; never assume the user cloned the35Flink Agents repository. Resolve bundled paths relative to this `SKILL.md`.3637Inspect the target version and conventions. Use sources in this order:38391. Target application code, dependency metadata, installed package/JAR APIs, and tests.402. Version-matching Flink Agents schema, docs, examples, or source when available.413. This skill's [YAML contract manifest](assets/yaml-contracts.yaml), matching42 bundled schema, and references as the offline baseline.4344Select contracts by the target Flink Agents version, not by the version that45published this skill. The manifest maps released versions to complete schemas and46marks versions without YAML support. The unversioned47[main schema](assets/yaml-schema.json) describes only the repository revision that48published this skill. Never validate a released application against that schema49unless the manifest maps the selected version to it.5051Do not invent APIs, versions, or commands from memory.5253Before presenting code as runnable, resolve every nontrivial import, constructor,54method, descriptor argument, and dependency coordinate against those sources. If a55contract cannot be resolved, either use a documented alternative or label the56fragment as pseudocode and state exactly what remains unresolved. Apply57[Provider Contract Triage](#provider-contract-triage) below to external58descriptor-backed Providers before loading bundled references. This blocked59Provider path is different from an unresolved business contract, which still60receives a user-fillable skeleton.6162## Preflight6364Before loading a platform adapter, asking a decision gate, or generating files:65661. Confirm that the target is a Flink Agents application or is being converted into67 one. Leave ordinary Flink jobs outside this workflow.682. Inspect the complete user request, existing project, dependency metadata, source,69 configuration, and tests. Resolve every framework decision already answered by70 that evidence. The latest explicit user choice takes precedence; treat a conflict71 with existing project metadata as an intentional requested migration and report72 it rather than silently restoring the old value.733. Record each required framework decision as `confirmed` or `unresolved`: Flink74 Agents version, Flink version, API, YAML application language when applicable,75 each descriptor-backed Resource implementation, and the Python environment when76 Python is required.774. Run Provider Contract Triage for every concrete external descriptor-backed78 Provider already named by the request or project. When the implementation is an79 unresolved gate, run the triage immediately after the user selects it.805. Build the ordered gate list from only the `unresolved` decisions. If the list is81 empty, skip host detection and interaction adapters and proceed directly to82 contract resolution and implementation.836. For YAML, select the exact target-version schema through84 [yaml-contracts.yaml](assets/yaml-contracts.yaml). Filter the API choices when the85 manifest says that the selected version has no YAML API. If a requested YAML86 version has no matching schema, stop YAML generation and request the exact87 target-version schema or source; never substitute the main schema.8889Keep this decision record current after every answer. It prevents repeated90questions and ensures that later references operate only on confirmed versions and91capabilities.9293### Provider Contract Triage9495This is an early-exit pass, not a later Build Workflow step. Run it as soon as a96concrete external descriptor-backed Provider class or alias is confirmed and before97reading any file under `references/`.9899Inspect only evidence that can establish that Provider's contract:1001011. Explicit user-supplied JARs, packages, source, tests, or documentation.1022. The target project's dependency metadata and the exact installed artifact named103 by that metadata.1043. Version-matching authoritative Provider source or documentation already available105 at a known location.106107Scope every inspection command to the target application's dependency files,108configuration, source roots, and explicitly named artifacts. Exclude the installed109Skill directory containing this `SKILL.md`, including project-local `.agents/`, and110exclude host metadata such as `.codex/`, `.claude/`, tool caches, and unrelated home111or package caches. Do not run an unscoped recursive search over `.` when it would112traverse those paths.113114Do not load general application, YAML, language, local-development, or verification115references to compensate for a missing Provider artifact. A general YAML schema can116validate descriptor shape but cannot establish a Provider's dependency coordinate,117constructor, or forwarded mandatory arguments. When the user explicitly states that118no Provider artifact or contract source is available, treat that as evidence; check119the target project metadata for an existing dependency, but do not search unrelated120caches or examples.121122The triage must establish the implementation class or alias, dependency coordinate123or package, constructor/factory contract, and every mandatory descriptor argument.124If any element remains unverifiable:125126- preserve all working dependency, source, and configuration files;127- stop the dependent integration immediately, before the normal Build Workflow;128- do not generate a descriptor, adapter, wrapper, placeholder dependency, or tests;129- report the exact sources checked, each missing contract element, and the minimum130 JAR, package, source, test, or documentation needed to continue.131132List a source under `checked` only when its content was actually inspected during133the triage. Do not claim that a bundled schema, reference, cache, or documentation134was checked merely because `SKILL.md` names it.135136Return that blocked report for a Provider-only request. Continue other work only137when the user explicitly requested an independent change that does not depend on the138blocked Provider. If the complete Provider contract is verified, proceed with the139normal workflow using that evidence.140141## Definition Strategy142143| Situation | Recommendation |144|---|---|145| New Workflow Agent or rewired event graph | Offer YAML plus Python/Java implementation files |146| Existing YAML application | Preserve and extend YAML |147| Existing programmatic Agent | Preserve its current API unless conversion is requested |148| `ReActAgent`, unsupported YAML surface, or explicit code-only request | Direct Python or Java API |149150For a new application, derive the available API choices from the confirmed target151version. Present YAML, direct Python API, and direct Java API when all three are152supported; otherwise omit unsupported surfaces. A recommendation explains the153tradeoff; it is not permission to select the API for the user.154155YAML does not declare an agent `type`. Do not add `type: workflow` or156`type: react`; `type` selects an implementation language where the schema allows it.157158YAML does not choose the business implementation language either. For a new YAML159application, ask the user to choose Python or Java before generating files. For an160existing application, detect and preserve the language from build metadata, source161files, function references, and explicit YAML `type` fields. Do not default to162Python merely because omitted YAML `type` fields currently resolve to Python.163164Workflow Agents already include built-in chat, tool-call, and context-retrieval165Actions. A model reasoning/tool loop can therefore remain YAML-defined. Choose166`ReActAgent` only when the user explicitly wants that programmatic abstraction, the167existing application already uses it, or a required ReAct-specific surface is not168available through YAML.169170## Scaffolding Boundary171172Complete framework-owned wiring, but do not invent business behavior. Before173implementing each custom Action, Tool, domain client, data transformation, Prompt,174or runtime Skill, classify these contract elements from only explicit user175requirements, existing code, and existing tests:176177| Contract element | `supplied` means |178|---|---|179| Input | Required fields and their meaning are defined |180| Output | Result fields or emitted Events are defined |181| Transformation | Input-to-output or message construction is defined |182| Side effects | External calls, state changes, and authentication boundary are defined |183| Errors | Required failure and fallback behavior is defined |184185Anything not established by those sources is `unresolved`; a high-level capability186name is not a supplied contract. When behavior depends on an unresolved element,187generate only an importable or compilable signature skeleton with focused TODOs and188an explicit `NotImplementedError` or `UnsupportedOperationException`. Preserve189user-provided names, parameters, types, and descriptions. When those are absent,190derive a stable capability name and use the narrowest framework-compatible191signature; for a function Tool or domain client with no typed contract, use one192opaque string request and string result.193194An unresolved skeleton must not emit business Events, transform payloads, compose195Prompt or chat messages, call a backend, return business data, or provide fallback196behavior. Tests may check import/compilation, signature and YAML reference197resolution, and explicit failure, but must not assert business behavior that was198not supplied.199200Do not author domain rules, REST endpoints, diagnostic procedures, prompts, data201models, Tool results, runtime Skill instructions, or test doubles from a high-level202application idea. Do not propose a standard REST API, MCP server, or mock backend as203the implementation of a custom Tool. Do not ask the user to lock a business input204identity schema, deployment platform, service API, authentication design, or log/205metric backend merely to scaffold the application. Generate the neutral skeleton206and leave those choices as TODOs for the user. Built-in Flink Agents Actions are207framework behavior and need no generated implementation.208209## Interaction Discipline210211This section is the sole authority for interaction capability detection, fallback212selection, retry behavior, and host-mode handling. Platform adapters only describe213how to encode a question for a tool that this section selected; other references214must point here instead of restating this policy.215216Process the unresolved decisions from Preflight as sequential gates. Ask only the217current gate, wait for the answer, update the decision record, and continue. Never218send one proposed baseline that bundles versions, API, implementation language,219runtime version, Resource implementations, business backends, and mock behavior.220221Only when at least one unresolved closed gate remains, identify the current host222from explicit system and tool context. Use this table to select the sole candidate223tool and adapter for the gate:224225| Host | Candidate structured tool | Adapter |226|---|---|---|227| Codex | `request_user_input` | [codex.md](references/platforms/codex.md) |228| Claude Code | `AskUserQuestion` | [claude-code.md](references/platforms/claude-code.md) |229| Gemini CLI | `ask_user` communication tool | [gemini-cli.md](references/platforms/gemini-cli.md) |230| Qoder | Explicitly exposed structured single-select tool, if any | [qoder.md](references/platforms/qoder.md) |231| Unknown or unsupported | Explicitly exposed structured single-select tool, if any | [generic.md](references/platforms/generic.md) |232233Treat the current tool contract as the only capability signal. When the table's234candidate is exposed and callable, read its adapter to encode one question. An235adapter must not perform capability discovery or select a fallback. If the candidate236is absent, returns an availability error, or cannot represent the complete valid237option set without altering or obscuring it, immediately read238[generic.md](references/platforms/generic.md) and use its numbered fallback. Do not239retry the tool, ask the user to change modes, require a slash command or keyboard240shortcut, perform a post-interview handoff, add host metadata, or install host241configuration in the generated application.242243Never use an open-ended text question when the valid options are already known.244When a gate has a recommendation, place it first and label it `(Recommended)`, but245do not preselect or continue without the user's answer. The YAML246implementation-language gate intentionally has no recommendation: present Python247and Java as equal peer options with parallel descriptions and no `(Recommended)`248label.249250Use this order:2512521. If unresolved, ask for the Flink Agents version and wait. Then offer only253 compatible Flink versions and wait for the Flink choice. Do not mention254 Python/JDK versions, an Agent API, a model provider, or business architecture in255 these version questions.2562. If unresolved, ask the user to choose among the APIs supported by the confirmed257 Flink Agents version. Offer YAML only when its exact contract is available. Wait.2583. Only when YAML is selected, ask whether custom Actions, function Tools, and the259 Flink entry point use Python or Java. Resource implementations are selected260 independently at their own gates. Direct Python or Java API already determines261 the application-code choice. Do not recommend, preselect, or imply a preference262 for either YAML implementation language. Only now resolve a compatible Python or263 JDK version.2644. Inventory the Resources required by the user's stated design. Resolve real265 descriptor-backed framework integrations one at a time and wait before moving to266 the next integration. Assign a deterministic internal name, ask for its267 implementation class or documented alias, and stop the interview for that268 Resource. Immediately run Provider Contract Triage after the implementation269 choice; it verifies the target-version constructor and descriptor. If it passes,270 generate every mandatory configuration key as `TODO_REQUIRED_<FIELD>` for the271 user to fill. Do not ask about another Resource or load general references before272 the triage result.273 For chat-model connections/setups, embedding-model connections/setups, and vector274 stores, do not filter candidates by the Agent API or application-code language.275 Present all verified Python and Java implementations, label each candidate's276 implementation language when needed for disambiguation, and generate the matching277 bridge declaration and runtime dependencies after selection.278 Do not ask for model identifiers, endpoints, credential values/mechanisms,279 provider options, Skill source paths/URLs/packages, or other Resource arguments.280 Custom Actions, function Tools, domain clients, Prompt content, runtime Skill281 instructions, business input schemas, and backend platforms are not integration282 gates: scaffold them without a business interview. Do not ask the user to name a283 single Resource or repeat a generated reference. Ask about naming only when284 multiple Resources need semantic disambiguation, an existing external reference285 constrains the name, or the user requested a naming convention.2865. As soon as the confirmed design first requires a Python runtime, pause before287 environment creation or dependency installation. Unless the existing project288 already declares its environment unambiguously, inspect compatible local Python289 executables/environments and ask whether to reuse one of them or create a290 project-local `.venv`. Wait for the choice and use the selected interpreter for291 every install, import, test, and local run. This conditional gate fires292 immediately after the choice that introduces Python; do not delay it until the293 end of the Resource interview.2946. After every framework decision is confirmed, design the Action graph and generate295 the project. Do not add a host-specific handoff.296297Do not infer OpenAI, Ollama, any model name, an environment-variable credential,298Skill distribution, MCP, a vector store, or a domain-service protocol. After a299framework implementation is selected, do not run a second configuration interview.300Generate a declaration or builder scaffold that names every verified mandatory301argument and leaves its value explicit for the user. For YAML string fields, use a302clear placeholder such as `TODO_REQUIRED_API_KEY`; for direct APIs, generate a303compilable factory skeleton that lists the required arguments and fails explicitly304until they are filled. If the user already supplied a value or explicitly requested305plaintext in local YAML, use that instruction; keep supplied secrets out of tracked306files and output. Never claim `${ENV_VAR}` is interpolated unless the target loader307or provider actually implements it.308309The conditional Python-environment gate is dependency management, not Resource310configuration. It still runs when a selected Resource introduces Python, but it asks311only which concrete compatible Python environment to use, never provider values.312313## Build Workflow3143151. Run Preflight, including Provider Contract Triage for every concrete external316 Provider already named by the request or project. If a Provider is blocked, issue317 its report and stop before reading any bundled reference.3182. Read [application patterns](references/application-patterns.md), then ask only the319 ordered unresolved gates. Do not repeat decisions already confirmed by the user320 or project.3213. When versions are unresolved, complete the version gates in322 [local development](references/local-development.md): Flink Agents first, then a323 compatible Flink version. Do not generate files or combine later decisions into324 these questions.3254. Complete the API gate with only APIs supported by the confirmed target version.326 For YAML, read [YAML patterns](references/yaml-patterns.md), select the exact327 schema through [yaml-contracts.yaml](assets/yaml-contracts.yaml), and reject328 generation when no exact contract is available.3295. If YAML was selected, complete the implementation-language gate. Then read330 [Python patterns](references/python-patterns.md) or331 [Java patterns](references/java-patterns.md) for the application code. When a332 bridge-supported Resource uses the other language, also read that language's333 cross-language Resource section; selecting that Resource is already explicit334 confirmation.3356. Inventory each Resource and assign stable names automatically. Ask only which336 documented implementation alias/class to use for actual framework integrations.337 For bridge-supported types, build this choice from both Python and Java338 implementations instead of the application-code language alone. Inspect the339 selected implementation through Provider Contract Triage before loading more340 references or moving to another integration. When it passes, add its integration341 and bridge dependencies and scaffold all mandatory configuration keys without342 asking for their values.343 Classify every custom Tool/Action/Prompt/runtime-Skill business contract before344 generating its skeleton; do not ask the user to choose a domain platform or345 complete an unresolved input contract. Generate and record all cross-references346 without asking the user to repeat internal identifiers. Never select a provider,347 model, endpoint, credential source, business backend, or integration from the348 application domain alone.3497. When runtime Skills are requested, preserve an explicit source in an existing350 application. For a new application, generate a minimal runtime `SKILL.md` business351 scaffold plus a source-configuration TODO that lists the valid `paths`, `urls`,352 Python `package`, and Java `classpath` forms. Do not ask for loading paths or353 distribution, and never inspect, copy, or offer to reuse Skills installed in the354 coding-agent host, such as a local `flink-diag`; coding-agent Skills and Flink355 runtime Skills are different artifacts. Read356 [YAML patterns](references/yaml-patterns.md#runtime-skills).3578. Draw only framework Action graph edges established by built-in contracts or358 supplied business contracts. Where an emitted Event, payload transformation,359 branch, output, or error contract is unresolved, generate the Action signature360 and explicit failure but do not claim or implement that edge. Do not turn those361 TODOs into more gates.3629. Use only documented built-in Actions. Generate a resolvable, correctly typed363 signature skeleton for every other Action and reference it as364 `<module-or-class>:<qualname>`; leave its business body for the user unless they365 explicitly requested implementation.36610. Resolve concrete API calls and dependency coordinates from the target-version367 artifacts before generating the complete executable project. For Java, generate368 a Maven project with369 `flink-agents-api`, `flink-agents-plan`, `flink-agents-runtime`, and only the370 integrations actually used; declare all Flink Agents and Flink dependencies as371 `provided`. Whenever the design requires Python, generate source and dependency372 files, resolve the Python environment choice when not already declared, and373 install the resolved Flink Agents, PyFlink, and integration dependencies into the374 selected existing environment or project-local `.venv`. Read375 [local development](references/local-development.md). Preserve versions already376 selected by the target project; never guess one.37711. Connect the Agent to a Flink DataStream or Table through the public factory backed378 by `RemoteExecutionEnvironment`. Local validation submits that same remote-style379 job to a MiniCluster. Never use a local Agents environment, a no-argument factory,380 `from_list`/`to_list`, or their Java equivalents.38112. Run the checks in [verification](references/verification.md) before claiming382 the application is valid or runnable.383384## Required Output385386- Complete framework files or edits, including every custom function signature and387 a remote-style Flink job entry point.388- A runnable Maven project for Java and, whenever Python is required, pinned Python389 dependency input plus the user-selected existing environment or populated390 project-local `.venv`.391- User-confirmed Flink Agents and Flink versions. Never silently choose the bundled392 recommended versions for a new project.393- A user-confirmed API choice from the surfaces supported by the selected Flink394 Agents version.395- A user-confirmed Python or Java application-code language for every new YAML396 application, reflected consistently in project layout, custom Action/Tool function397 references, and the Flink entry point. Do not use it to filter bridge-supported398 Resource implementations.399- For applications using runtime Skills, a user-fillable Skill business scaffold400 and source-configuration TODO. Preserve existing source configuration, but do not401 ask a new-project user to choose distribution or reuse coding-agent host Skills.402- Resource declarations built from user-selected implementation aliases/classes,403 including independent Resource implementation language and bridge wiring where404 supported, with every verified mandatory provider key present and marked for user405 input.406 Keep model, endpoint, credential, and optional provider values unresolved instead407 of interviewing for them or choosing defaults.408- Deterministic Resource names and references generated by the coding agent. Do not409 require the user to name ordinary Connection, Setup, Prompt, Skill container,410 VectorStore, or MCP Resource identifiers when there is no ambiguity.411- When the user chooses plaintext credentials for local testing, a loader-compatible412 local YAML that is excluded from version control and actually used by the local413 run command. Do not replace this explicit choice with programmatic registration.414- Explicit user-fillable business skeletons for custom Actions, Tools, prompts,415 runtime Skills, domain clients, secrets, endpoints, and external data, backed by416 the supplied/unresolved contract classification. Keep framework wiring and417 signatures concrete instead of replacing them with fabricated business418 implementation.419- A final consolidated `User must provide` list for unresolved business input420 fields, platform clients, authentication, queries, response mapping, and domain421 behavior. These items must not block project scaffolding or become Agent workflow422 decisions unless the user explicitly asks for their implementation.423- Exact commands that match the target repository's build tooling; no guessed424 package, Flink, provider, model, or plugin versions.425- Framework snippets whose imports and API calls resolve in the target version.426 Business skeletons must import or compile, fail explicitly when invoked, and be427 labeled user-fillable rather than runnable behavior.428- For YAML, the selected contract key and exact schema path used for validation.429- Evidence separated into schema, load/compile, tests, and runtime.430- A clear statement for every check that was not run or requires an external service.431432## Quick Reference433434| Task | Read |435|---|---|436| Present closed choices in the current coding agent | [Interaction Discipline](#interaction-discipline), then its selected platform adapter |437| Select Agent/API shape; design Resources and event graph | [application-patterns.md](references/application-patterns.md) |438| Author or review YAML; resolve names and functions | [yaml-patterns.md](references/yaml-patterns.md) |439| Scaffold runtime Skill business and source TODOs | [runtime Skills](references/application-patterns.md#scaffold-runtime-skills) |440| Scaffold Python Actions, Tools, types, or runner | [python-patterns.md](references/python-patterns.md) |441| Scaffold Java Actions, Tools, resources, or runner | [java-patterns.md](references/java-patterns.md) |442| Select versions, generate dependencies, and submit to MiniCluster | [local-development.md](references/local-development.md) |443| Validate schema, references, imports, compilation, and execution claims | [verification.md](references/verification.md) |444| Select and validate YAML without a source checkout | [YAML contract manifest](assets/yaml-contracts.yaml) |